---
doc_id: DDS-202606-002
feature_id: FEAT-202606-002-fastgpt-integration
type: detailed-design
title: 医梦 AI 中台接入 FastGPT 设计与技术方案
status: reviewing
owner: 医梦研发团队
created_at: 2026-06-13
updated_at: 2026-06-13
reviewers: []
related_docs:
  - ODS-202606-001
related_modules:
  - emoon-openplatform
  - emoon-ai-agent
  - emoon-ai-mcp
  - emoon-ai-file
tags:
  - FastGPT
  - Agent Adapter
  - MCP Gateway
  - 知识库
---

# 医梦 AI 中台接入 FastGPT 设计与技术方案

| 项目 | 内容 |
| --- | --- |
| 文档定位 | 公司评审版设计 + 技术方案 |
| 适用范围 | 医梦 AI 开放平台、AI Agent、FastGPT Adapter、MCP Gateway、Card Runtime、File Service、知识库运行副本、计量审计 |
| 目标读者 | 公司管理层、商务谈判团队、架构评审人员、后端开发、初级工程师 |
| FastGPT 源码基线 | `/Users/destiny/dev/emoon/projects/FastGPT`，本地 checkout `ga6885b339`（基于 `v4.15.0-beta`，上游 `Latest` 稳定 release 为 `v4.14.24`；另有 `v4.15.0-beta4` 预发布） |
| emoon 工程基线 | Java 17 / Spring Boot 3 / Maven 多模块，AI 能力按 `emoon-ai-*` 分层模块落位 |
| 版本 | v2.0 |
| 更新时间 | 2026-06-13 |

## 0. 阅读结论

本方案的核心结论是：

```text
FastGPT 可以作为医梦 AIAgent 的实现层之一接入，
但不能替代医梦 AI 中台，也不能成为医院业务系统的入口。
```

正确架构是：

```text
外部入口 / 终端 / 医生端 / 患者端 / 医院系统
        ↓
医梦 OpenPlatform + 医疗智能体应用控制层
        ↓
医梦 FastGPT Adapter
        ↓
FastGPT AI 能力层
```

错误架构是：

```text
外部入口 / 医生端 / 患者端 / HIS / LIS / EMR / 设备
        ↓
FastGPT
```

FastGPT 在本项目中的定位是“后方 AI 能力底座”，主要承接：

- LLM 生成；
- Workflow 子流程；
- RAG 检索；
- OCR / 多模态理解；
- Embedding / Rerank；
- 知识库运行副本；
- AI 调用日志和资源消耗数据。

医梦必须保留并强化：

- 外部入口和统一鉴权；
- 医疗场景路由；
- 任务状态机；
- 卡片运行时；
- 医梦 MCP Gateway；
- HIS / LIS / EMR / PACS / 支付 / 叫号等医院系统适配；
- 文件源资产和敏感数据控制；
- 医生反馈闭环；
- 知识库源资产管理；
- 计量、账本、审计、合同和运营闭环。

## 1. 本文修正 Claude 初稿的关键点

Claude 初稿提供了有价值的方向，但有几处需要在公司评审前修正。

| 初稿说法 | 本文修正 | 原因 |
| --- | --- | --- |
| FastGPT 版本口径混用 | 本地 checkout `ga6885b339`，基于 `v4.15.0-beta`；上游 `Latest` 稳定 release 为 `v4.14.24`，另有 `v4.15.0-beta4` 预发布 | 文档必须同时标注本地源码基线、稳定版能力和 beta 能力差异 |
| `~/dev/emoon/project/FastGPT` | `/Users/destiny/dev/emoon/projects/FastGPT` | 实际目录为 `projects`，不是 `project` |
| Dify 尚未进入代码，切换成本极低 | emoon 已存在 `DifyAgentEngine`、`DifyKnowledgeEngine`、Dify 意图识别和多处 `dify` 硬编码 | 切换不是零成本，需要双引擎并存和逐步迁移 |
| FastGPT OpenAI-compatible，可直接复用 DirectLLM 协议 | 只能复用部分请求/流式解析思想，不能完全当作 OpenAI API | FastGPT `model/temperature` 等参数由编排决定，API 参数不按 OpenAI 语义生效 |
| FastGPT `usage` 可直接用于计量 | 不可信任默认 `usage` | v1 接口默认 `usage` 为占位值，需要 `detail=true.responseData` 或日志归集 |
| FastGPT 社区版能力完整 | 必须区分社区版、商业版、云服务版 | 运行日志看板、应用评测、内容审核、SSO、多租户等能力与商业版相关 |
| 很多 emoon 模块无需修改 | 对外入口不改，但知识库、意图识别、引擎配置、计量归集、健康探活都需要适配 | 当前代码存在 Dify 语义绑定 |

## 2. 背景与决策问题

### 2.1 业务背景

甲方本周明确提出希望底层 AI 中台替换为 FastGPT。考虑到 FastGPT 与 Dify 都提供通用 AI 应用构建、Workflow、RAG、工具调用和模型编排能力，医梦不能把二期和三期规划整体推倒重来。

更合理的理解是：

```text
Dify / FastGPT / DirectLLM / Mock
都是 AgentEngine 的实现层。
医梦 AI 中台的医疗业务控制层不能被替换。
```

### 2.2 评审要回答的问题

本方案需要回答四类问题：

1. FastGPT 现有能力是什么，哪些能力可用，哪些能力有版本或商业限制；
2. Dify 与 FastGPT 在产品、工程接入、医疗业务闭环上的差异；
3. 相比原 Dify 规划，接入 FastGPT 会产生哪些限制和新问题；
4. emoon 应如何分阶段接入 FastGPT，并控制风险、边界和工程复杂度。

### 2.3 总体建议

建议采用“FastGPT 主接入 + Dify 过渡保留”的策略：

- 新增 `engineType=fastgpt`，不要删除 `engineType=dify`；
- 新项目优先验证 FastGPT；
- 已经跑通的 Dify 链路不立即强拆；
- 管理后台、Agent 配置、知识库配置、意图识别配置逐步从硬编码 `dify` 改为可配置引擎；
- 计量、审计、卡片、文件和 MCP 网关坚持由 emoon 控制。

## 3. FastGPT 能力全景

本节基于本地 FastGPT 源码和文档目录校准，不默认把商业版能力算入 P0。

### 3.1 产品定位

FastGPT 是一个 AI 应用构建平台，核心能力包括：

- 应用编排；
- 智能体对话；
- Workflow；
- 知识库；
- MCP 工具集；
- HTTP 工具集；
- OpenAPI 调用；
- 分享和嵌入；
- 模型配置；
- 部署运维。

技术栈：

- Node.js / TypeScript；
- Next.js；
- MongoDB；
- Docker / Sealos 部署体系。

### 3.2 应用类型

本地源码中 `AppTypeEnum` 关键值如下：

| 类型 | 源码枚举值 | 说明 | emoon 用法 |
| --- | --- | --- | --- |
| 简易对话 | `simple` | FAQ、普通问答 | P0 可用 |
| 对话智能体 | `chatAgent` | 带工具和上下文的对话 | P0 可用 |
| Workflow | `advanced` | 高级编排 | P0/P1 主能力 |
| Workflow Tool | `plugin` | 可复用插件流程 | P1 可用 |
| MCP ToolSet | `toolSet` | MCP 工具集 | P1 重点验证 |
| HTTP ToolSet | `httpToolSet` | HTTP 工具集 | P1/P2 可选 |
| 文件夹 | `folder` / `toolFolder` | 管理组织结构 | 管理后台可见 |

初级工程师注意：

```text
FastGPT 的 workflow 类型在源码枚举中叫 advanced。
不要只看 UI 文案写死字符串。
```

### 3.3 对话能力

核心接口：

```text
POST /api/v1/chat/completions
POST /api/v2/chat/completions
POST /api/v2/chat/stop
```

本文 P0 建议先接 `v1`，原因是现有文档和源码中的兼容性说明更充分。后续可在 P1 评估 v2。

`v1` 请求关键字段：

```json
{
  "chatId": "emoon-conversation-id",
  "stream": true,
  "detail": true,
  "responseChatItemId": "emoon-message-id",
  "variables": {
    "traceId": "trace_xxx",
    "sceneCode": "OUTPATIENT_TRIAGE"
  },
  "messages": [
    {
      "role": "user",
      "content": "我头疼应该挂什么科"
    }
  ]
}
```

重要差异：

| 点 | 说明 | emoon 影响 |
| --- | --- | --- |
| `model` | FastGPT v1 文档说明 `model` 等参数无效，实际应用由鉴权和编排决定 | 不要用 `model` 表达 FastGPT App ID 的唯一来源 |
| `temperature` | 由 FastGPT 编排配置决定 | emoon 不应在运行时假设可覆盖 |
| `chatId` | 不传时不使用 FastGPT 上下文；传入时 FastGPT 会按 chatId 取历史 | emoon 应传自己的会话 ID 或映射 ID |
| `detail` | 返回节点执行过程和 responseData | 计量、审计、调试建议开启或按环境开启 |
| `usage` | v1 默认响应里可能是占位值 | 不能直接入账 |

### 3.4 流式 SSE 能力

FastGPT `stream=true` 时返回 SSE。普通增量类似：

```text
data: {"choices":[{"delta":{"content":"您"},"finish_reason":null}]}
data: {"choices":[{"delta":{"content":"好"},"finish_reason":null}]}
data: [DONE]
```

当 `detail=true` 时，还会出现流程节点结果事件。emoon 需要做两层归一化：

1. FastGPT SSE → `AgentResponse`；
2. `AgentResponse` → OpenPlatform 对外 SSE 事件。

emoon 对外仍保持：

```text
message_delta
message_completed
journey_updated
task_updated
card_created
completed
error
```

FastGPT 原始 SSE 事件不能直接暴露给终端厂商。

### 3.5 知识库能力

FastGPT 知识库能力包括：

- 创建知识库；
- 查询知识库列表和详情；
- 文件集合管理；
- 文档导入；
- 分段管理；
- 检索测试；
- 训练订单；
- 图片和多模态相关增强能力。

需要区分版本：

| 能力 | 社区版 | 商业版/云服务版 | emoon 建议 |
| --- | --- | --- | --- |
| 基础知识库 | 支持 | 支持 | P1 可接 |
| 文档导入 | 支持 | 支持 | P1 可接 |
| 知识库索引增强 | 受限 | 支持 | 不作为 P0 承诺 |
| Web 站点同步 | 受限 | 支持 | 不作为 P0 承诺 |
| 第三方知识库同步 | 受限 | 支持 | 商务确认后再排期 |
| 图片知识库 | 受限 | 支持 | 医疗影像/舌象不能直接依赖 |

医梦的原则：

```text
emoon 保存知识库源资产。
FastGPT 保存运行副本。
医生反馈先进入 emoon，再决定是否更新 FastGPT 知识库。
```

### 3.6 MCP 能力

FastGPT 源码中 `packages/service/core/app/mcp.ts` 使用：

- `@modelcontextprotocol/sdk`；
- `StreamableHTTPClientTransport`；
- `SSEClientTransport`；
- `listTools`；
- `callTool`；
- 工具调用超时约 300 秒；
- `isInternalAddress()` 内网地址防护；
- JSON Schema `$ref` 解析时禁用 file/http，降低 SSRF 风险。

这是 FastGPT 相比 Dify 的重要优势，但也带来边界风险。

医梦规定：

```text
FastGPT MCP Client 只能连 emoon MCP Gateway。
FastGPT 不能直接连 HIS / LIS / EMR / PACS / 支付 / 叫号 / 设备平台。
```

### 3.7 版本能力

FastGPT 源码存在：

```text
/api/core/app/version/list
/api/core/app/version/publish
/api/core/app/version/detail
/api/core/app/version/latest
/api/core/app/version/update
```

能力可用于版本列表、发布、详情、最新版本和更新。但 emoon 不应完全依赖 FastGPT 作为医疗场景版本事实源。

emoon 需要额外保存：

- `agentId`；
- `fastgptAppId`；
- `fastgptVersionId`；
- FastGPT App 快照；
- emoon 输出 Schema 版本；
- 生效状态；
- 灰度策略；
- 回滚指针。

### 3.8 运营和日志能力

FastGPT 可提供应用运行数据和模型调用数据，但公司评审要注意：

| 能力 | 风险 |
| --- | --- |
| 运行日志看板 | 商业版能力，不应默认进入 P0 |
| 应用评测 | 商业版/云服务版能力更完整 |
| 内容审核 | 商业版能力，不应替代 emoon 医疗安全规则 |
| 模型日志 | 可用于辅助对账，但不能替代 emoon 计量账本 |
| 用户反馈 | 可用作辅助标注，但医生反馈主链路必须在 emoon |

### 3.9 emoon 主调用 FastGPT API 清单

完整 FastGPT route 明细见 [附录 A](#附录-a-fastgpt-当前源码-api-明细)。正文只保留 emoon 需要纳入架构评审、接口设计和工程排期的主调用接口族；这些接口必须经由 `FastGPT Adapter` 封装，业务模块不得直接散落调用 FastGPT。

| 功能域 | 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
|--------|------|--------------|--------------------|--------------------------|
| 对话运行 | `POST /api/v1/chat/completions` | FastGPT OpenAI 风格主对话入口，支持同步/流式输出、`chatId`、`variables`、`detail` 等运行参数 | 是，P0 | 是，作为 `FastGptAgentEngine` 主入口 |
| 对话运行 | `POST /api/v2/chat/completions` | v2 对话入口，能力随 FastGPT 版本演进，适合后续评估替换 v1 | 暂不 P0 | 否，先以 v1 稳定接入为准 |
| 对话运行 | `POST /api/v2/chat/stop` | 停止运行中的会话任务，用于前端取消生成或超时熔断 | 是，P1 | 需要，SSE/长任务体验完善后接入 |
| 对话详情 | `POST /api/core/chat/getResData` | 获取运行详情、节点响应、引用数据等，用于弥补默认 `usage` 占位问题 | 是，P0 | 是，计量、审计、问题排查必须使用 |
| 对话详情 | `POST /api/core/chat/record/getResData` | 按历史记录查询单次响应明细 | 是，P1 | 需要，用于医生反馈回放和审计抽查 |
| 对话记录 | `POST /api/core/chat/getPaginationRecords` | 查询会话分页记录 | 可选 | 当前不作为事实源，仅用于排查 |
| 对话记录 | `POST /api/core/chat/record/getPaginationRecords` | 查询记录级分页列表 | 可选 | 当前不作为事实源，仅用于后台诊断 |
| 对话恢复 | `POST /api/core/chat/resume` | 恢复中断的对话运行 | 可选 | 仅在 FastGPT 工作流存在人工中断/恢复场景时接入 |
| 文件上传 | `POST /api/core/chat/file/presignChatFilePostUrl` | 获取聊天文件上传预签名地址 | 谨慎对接 | 仅允许 emoon File Service 代办，医生端/患者端不得直传 FastGPT |
| 文件下载 | `POST /api/core/chat/file/presignChatFileGetUrl` | 获取聊天文件下载预签名地址 | 谨慎对接 | 仅用于受控回放和审计，不作为长期文件地址 |
| 反馈 | `POST /api/core/chat/feedback/updateUserFeedback` | 写入用户反馈、点赞点踩或纠错信息 | 是，P1 | 需要，但医生反馈仍须先落 emoon 反馈表 |
| 应用详情 | `POST /api/core/app/detail` | 获取 FastGPT 应用完整配置详情 | 是，P0 | 是，用于配置校验和版本映射 |
| 应用信息 | `POST /api/core/app/getBasicInfo` | 获取应用基础信息 | 是，P0 | 是，用于健康检查和后台展示 |
| 应用权限 | `POST /api/core/app/getPermission` | 查询应用访问权限 | 是，P1 | 需要，用于发布前校验 |
| 应用列表 | `GET /api/core/app/list` | 查询应用列表 | 可选 | 管理后台可用，运行链路不依赖 |
| 应用版本 | `GET /api/core/app/version/list` | 查询应用版本列表 | 是，P0 | 是，支撑 emoon 版本映射和回滚 |
| 应用版本 | `GET /api/core/app/version/detail` | 查询指定应用版本详情 | 是，P0 | 是，发布审计和差异比对需要 |
| 应用版本 | `GET /api/core/app/version/latest` | 查询最新版本 | 是，P0 | 是，但不能自动替换 emoon 生效版本 |
| 应用发布 | `POST /api/core/app/version/publish` | 发布 FastGPT 应用版本 | 谨慎对接 | 仅允许 emoon 管理后台受控触发，不允许运营直接绕过版本映射 |
| 应用日志 | `POST /api/core/app/logs/list` | 查询应用运行日志 | 是，P1 | 需要，用于联调、灰度和线上问题定位 |
| 应用日志 | `POST /api/core/app/logs/exportLogs` | 导出应用日志 | 可选 | 审计导出场景需要，默认不进入 P0 |
| MCP 工具 | `POST /api/core/app/mcpTools/getTools` | 查询应用可用 MCP 工具 | 是，P1 | 需要，用于验证 FastGPT 只能看到 emoon MCP Gateway 暴露的工具 |
| MCP 工具 | `POST /api/core/app/mcpTools/getChildren` | 查询 MCP 工具子级/明细 | 是，P1 | 需要，用于工具权限巡检 |
| MCP 工具 | `POST /api/core/app/mcpTools/create` | 在 FastGPT 内创建 MCP ToolSet 应用，绑定远端 MCP Server URL、请求头密钥和工具列表 | 是，P1 | 需要，但只能注册 emoon MCP Gateway 或其受控代理地址 |
| MCP 工具 | `POST /api/core/app/mcpTools/update` | 更新 FastGPT MCP ToolSet 的 URL、密钥和工具列表 | 是，P1 | 需要，必须由 emoon 发布流程触发并记录版本 |
| MCP 工具 | `POST /api/core/app/mcpTools/runTool` | 通过 FastGPT 临时调用远端 MCP 工具，常用于配置验证和调试 | 谨慎对接 | 当前只用于验收测试，不进入生产业务主链路 |
| MCP Server | `GET /api/support/mcp/list` | 查询 FastGPT 对外暴露的 MCP Server 配置 | 可选，P2 | 当前不作为医梦医疗工具入口，只用于评估 FastGPT 应用被外部调用 |
| MCP Server | `POST /api/support/mcp/create` | 将若干 FastGPT 应用包装成 MCP Server 工具对外暴露 | 可选，P2 | 非 P0；不能替代 emoon 医疗工具网关 |
| MCP Server | `PUT /api/support/mcp/update` | 更新 FastGPT MCP Server 名称和绑定应用列表 | 可选，P2 | 非 P0；如使用必须纳入版本审计 |
| MCP Server | `DELETE /api/support/mcp/delete` | 删除 FastGPT MCP Server 配置 | 可选，P2 | 非 P0 |
| MCP Server | `POST /api/mcp/app/[key]/mcp` | FastGPT 提供的 MCP 协议端点，外部 MCP Client 可通过 key 调用被绑定的 FastGPT 应用工具 | 可选，P2 | 只适合把 FastGPT 应用暴露给 emoon 或内部工具，不面向医院系统 |
| OpenAPI Key | `POST /api/support/openapi/create` | 创建 FastGPT OpenAPI Key | 谨慎对接 | 建议由部署/运维初始化，生产运行不频繁调用 |
| OpenAPI Key | `GET /api/support/openapi/list` | 查询 OpenAPI Key 列表 | 是，P1 | 需要，用于配置巡检和密钥轮换检查 |
| 健康探活 | `GET /api/support/openapi/health` | OpenAPI 健康检查 | 是，P0 | 是，作为 Adapter 健康探活基础接口 |
| 知识库 | `GET /api/core/dataset/list` | 查询知识库列表 | 是，P0 | 是，用于运行副本映射和配置校验 |
| 知识库 | `POST /api/core/dataset/create` | 创建知识库 | 是，P1 | 需要，限管理后台/交付工具调用 |
| 知识库 | `GET /api/core/dataset/detail` | 查询知识库详情 | 是，P0 | 是，用于副本状态核验 |
| 知识库 | `POST /api/core/dataset/update` | 更新知识库配置 | 是，P1 | 需要，但必须由 emoon 知识资产发布流程触发 |
| 知识检索 | `POST /api/core/dataset/searchTest` | 对知识库执行检索测试 | 是，P1 | 需要，用于验收、召回质量评测和排障 |
| 知识集合 | `POST /api/core/dataset/collection/create/fileId` | 基于已上传文件创建知识集合 | 是，P1 | 需要，前提是文件先进入 emoon File Service 并完成脱敏/审计 |
| 知识集合 | `POST /api/core/dataset/collection/list` | 查询知识集合列表 | 是，P1 | 需要，用于同步状态和问题排查 |
| 知识分段 | `POST /api/core/dataset/data/list` | 查询知识分段数据 | 是，P1 | 需要，用于抽检、医生纠错和知识治理 |
| 训练队列 | `GET /api/core/dataset/training/getDatasetTrainingQueue` | 查询知识库训练队列 | 是，P1 | 需要，用于发布进度展示和失败重试 |
| 训练错误 | `GET /api/core/dataset/training/getTrainingError` | 查询训练错误 | 是，P1 | 需要，用于运维告警和交付排障 |
| 模型配置 | `GET /api/core/ai/model/list` | 查询 FastGPT 可用模型 | 是，P1 | 需要，用于环境验收，不作为业务模型事实源 |
| 模型测试 | `POST /api/core/ai/model/test` | 测试模型连通性 | 是，P1 | 需要，用于部署验收和健康诊断 |

对正文主调用接口的结论：P0 只覆盖对话主链路、应用版本映射、健康探活和知识库状态核验；P1 再补充文件受控流转、日志、反馈、训练队列、MCP ToolSet 注册、MCP 工具巡检和模型验收；FastGPT 自身的 MCP Server 暴露能力不进入医疗工具 P0，附录中大量用户、团队、市场、插件、初始化、迁移、商业版管理接口不应由 emoon 业务运行链路直接依赖。

### 3.10 emoon 调用 FastGPT 的功能价值评估

| 功能域 | emoon 是否调用 | 优先级 | 调用价值 | 边界与注意事项 |
| --- | --- | --- | --- | --- |
| 对话生成 `/v1/chat/completions` | 是 | P0 | 替代 Dify 承接 Agent 推理和 Workflow 子流程 | 只由 `FastGptAgentEngine` 调用，不暴露给终端 |
| SSE 流式 | 是 | P0 | 支撑统一入口客户端实时反馈 | 必须归一成 emoon SSE 事件 |
| `detail=true.responseData` | 是 | P0 | 获取节点级用量和调试信息 | 默认 usage 不可信，需二次归集 |
| 应用详情/探活 | 是 | P0/P1 | 验证 FastGPT App 和 API Key 可用 | 不作为业务配置事实源 |
| 应用版本 | 是 | P1 | 支撑灰度、回滚、审计 | emoon 仍保存版本映射和快照 |
| 应用日志 | 可选 | P1 | traceId 排障和计量对账辅助 | 不能替代 emoon 审计 |
| 知识库 CRUD | 是 | P1 | 同步知识库运行副本 | emoon 保存源资产，FastGPT 只运行检索副本 |
| 知识库检索测试 | 是 | P1 | 验证 RAG 效果 | 不直接面向医院用户 |
| MCP 工具集 | 可选 | P1 | 验证 FastGPT 能调用 emoon MCP Gateway | 不允许连接医院原始系统 |
| OpenAPI Key 管理 | 可选 | P1 | 交付和运维时创建/检查 Key | 生产运行建议用预置密钥和 emoon 配置管理 |
| 用户/团队 | 否 | - | FastGPT 平台内部能力 | emoon 自己维护医院项目和授权 |
| 外链发布 | 否 | - | FastGPT 自有发布渠道 | 医生端、患者端、终端入口必须走 emoon |
| 插件市场 | 否 | P2/P3 | 远期模板参考 | 医疗工具必须经 emoon 安全审查 |
| 沙箱/Skill | 否 | P2/P3 | 开发增强 | 不承载医疗生产业务代码 |
| FastGPT 文件接口 | 谨慎 | P1/P2 | 只用于 FastGPT 内部临时文件 | 医疗敏感文件必须先入 emoon File Service |

### 3.11 emoon 模块依赖 FastGPT 接口族架构图

下面的图只表达接口依赖关系，不表示所有接口都会进入 P0。实线是运行主链路，虚线是管理、运维、验证或后续增强链路。

```mermaid
flowchart TB
    Open["emoon-openplatform\n外部 API / SSE / 鉴权"]
    Agent["emoon-ai-agent\nFastGptAgentEngine / OutputNormalizer"]
    System["emoon-system / emoon-admin\n引擎配置 / 管理后台"]
    File["emoon-ai-file\n文件事实源 / 短期 URL"]
    Card["emoon-ai-card\nCard Runtime / Card Action"]
    Mcp["emoon-ai-mcp\nMCP Gateway / HIS Adapter"]
    Meter["emoon-ai-meter / billing\nUsage 归集 / 账本"]
    Audit["Audit / Operation\n审计 / 运营分析"]

    ChatApi["FastGPT 对话接口\n/v1/chat/completions"]
    ChatRead["FastGPT 会话/记录接口\n/core/chat/*"]
    AppApi["FastGPT 应用/版本/日志接口\n/core/app/*"]
    DatasetApi["FastGPT 知识库接口\n/core/dataset/*"]
    McpApi["FastGPT MCP/OpenAPI 接口\n/support/mcp/* /support/openapi/*"]
    PlatformApi["FastGPT 平台接口\nuser/team/outLink/plugin/admin/common/system"]

    Open --> Agent
    Agent --> ChatApi
    Agent -.断线恢复/排障.-> ChatRead
    System -.配置校验/版本映射.-> AppApi
    Agent -.应用版本/日志辅助.-> AppApi
    System -.知识库运行副本管理.-> DatasetApi
    Agent -.RAG 效果验证.-> DatasetApi
    File -.短期 URL / 脱敏摘要.-> Agent
    Agent --> Card
    Card --> Mcp
    ChatApi -.工具调用只能经网关.-> Mcp
    System -.OpenAPI Key / MCP 配置验证.-> McpApi
    McpApi -.只允许指向.-> Mcp
    Agent --> Meter
    ChatApi -.responseData / usage 明细.-> Meter
    Agent --> Audit
    AppApi -.运行日志辅助对账.-> Audit
    PlatformApi -.默认不接入医梦生产链路.-> System
```

模块依赖结论：

- `emoon-ai-agent` 是运行时唯一直接调用 FastGPT 对话接口的模块；
- `emoon-system / emoon-admin` 只做配置、探活、版本映射和知识库运行副本管理；
- `emoon-ai-file` 不调用 FastGPT，只给 Agent 提供可控文件引用；
- `emoon-ai-card` 不调用 FastGPT，只消费 Agent 归一后的卡片建议；
- `emoon-ai-mcp` 是 FastGPT 工具调用唯一可达的医院系统网关；
- `emoon-ai-meter / billing` 不读取 FastGPT 默认 usage 扣费，只消费 Adapter 提取后的节点用量和 emoon 自身事件；
- FastGPT 用户、团队、外链、插件市场、初始化迁移接口不进入当前医梦医疗生产链路。

## 4. Dify vs FastGPT 对比

### 4.1 产品能力对比

| 能力 | Dify | FastGPT | 结论 |
| --- | --- | --- | --- |
| Workflow | 成熟，生态大 | 支持 advanced Workflow | 基本对等 |
| Agent | 支持 | 支持 chatAgent | 基本对等 |
| RAG | 成熟 | 成熟，中文文档友好 | 基本对等 |
| MCP | 非原生或需适配 | 原生 MCP ToolSet | FastGPT 优势 |
| HTTP 工具 | 支持 | 支持 httpToolSet | 基本对等 |
| OpenAPI 调用 | 自有协议 | OpenAI-like | FastGPT 工程接入更接近标准 |
| 版本管理 | 发布/回滚语义较完整 | 有版本 API，但需校准 | Dify 更成熟 |
| 社区生态 | 更大 | 国内中文生态较强 | 取决于客户偏好 |
| 部署 | 依赖更多组件 | MongoDB 为主，部署相对轻 | FastGPT 部署较轻 |
| 开源协议 | Apache 2.0 | Apache 2.0 + 附加条件 | Dify 更宽松 |

### 4.2 工程接入对比

| 维度 | Dify 接入 | FastGPT 接入 | emoon 决策 |
| --- | --- | --- | --- |
| 对话请求 | `/v1/chat-messages` | `/api/v1/chat/completions` | 新增 `FastGptAgentEngine` |
| 输入变量 | `inputs` | `variables` | `AgentRequest.inputs` 映射到 `variables` |
| 会话 ID | Dify `conversation_id` | FastGPT `chatId` | emoon conversationId 仍为事实源 |
| 流式格式 | Dify 自有事件 | OpenAI-like SSE + detail 事件 | 统一由 Adapter 归一 |
| 用量 | metadata.usage | v1 usage 默认占位 | FastGPT 需特殊归集 |
| 知识库 API | 已有 `DifyKnowledgeEngine` | 需新增 `FastGptKnowledgeEngine` | P1 做 |
| 健康探活 | `/parameters` 可探 | 无统一稳定 health 端点 | 用最小对话或应用详情探活 |
| 意图识别 | 已有 `DifyIntentClient` | 需抽象成可配置 Intent Client | P1 做 |

### 4.3 医疗业务影响对比

| 医梦能力 | 使用 Dify | 使用 FastGPT | 是否改变 emoon 责任 |
| --- | --- | --- | --- |
| OpenPlatform 鉴权 | emoon 控制 | emoon 控制 | 不变 |
| 设备场景 | emoon 控制 | emoon 控制 | 不变 |
| TaskState | emoon 控制 | emoon 控制 | 不变 |
| Card Runtime | emoon 控制 | emoon 控制 | 不变 |
| MCP Gateway | emoon 控制 | emoon 控制 | 不变 |
| 计量账本 | emoon 控制 | emoon 控制 | 不变，但 FastGPT usage 解析更复杂 |
| 医生反馈 | emoon 控制 | emoon 控制 | 不变 |
| 知识库源资产 | emoon 控制 | emoon 控制 | 不变 |
| Workflow 子流程 | Dify 执行 | FastGPT 执行 | 实现层改变 |

## 5. emoon 当前 Dify 接入现状

### 5.1 已存在的 Dify 代码

当前工程已经不是“尚未接入 Dify”的状态。已发现的关键点：

| 类型 | 位置 | 说明 |
| --- | --- | --- |
| 对话引擎 | `emoon-ai-agent` 中 `DifyAgentEngine` | 已实现同步和 SSE |
| 知识库引擎 | `emoon-ai-agent` 中 `DifyKnowledgeEngine` | 已实现知识库、文档、分段、检索等大量 API |
| 意图识别 | `DifyIntentClient` | AgentRouter 可调用 Dify 意图智能体 |
| 管理后台连通性 | `AiEngineConnectivityClient` | 当前支持 `mock` 和 `dify` |
| OpenPlatform 旧客户端 | `emoon-openplatform/dify/*` | 仍有 DifyApiClient 和领域对象 |
| 知识库调用 | `KnowledgeBaseServiceImpl` / `KnowledgeBaseController` | 多处硬编码 `dify` |
| 应用对话服务 | `AgentChatApplicationServiceImpl` | 存在固定 Dify Agent ID 和 `getEngine("dify")` |

### 5.2 当前切换成本判断

切换成本不是零，但仍可控。

低成本部分：

- `AgentEngine` 已是可插拔接口；
- `AgentRequest` / `AgentResponse` 可以复用；
- `AgentEngineFactory` 可自动收集新实现；
- Card Runtime、Device、MCP、Meter 的目标边界已经存在；
- Maven 模块分层已为新实现预留位置。

中等成本部分：

- 知识库接口大量 Dify 语义需要抽象；
- 意图识别需要从 `DifyIntentClient` 泛化；
- 连通性测试和配置脱敏需要支持 FastGPT；
- OpenPlatform 中固定 Dify 逻辑需要迁移到领域层或配置层；
- FastGPT usage 不能直接入账。

高风险部分：

- 如果让 FastGPT 直接连接医院系统，会破坏医梦中台边界；
- 如果把 FastGPT Workflow 当作医疗主状态机，会导致审计、计量、回滚、人工确认不可控；
- 如果直接删除 Dify，会影响已有联调链路。

## 6. 目标架构与边界

### 6.1 五层架构

```mermaid
flowchart TB
    Entry["外部入口层\n小程序 / 医生端 / 终端 / 医院门户 / 第三方系统"]
    Open["医梦 OpenPlatform\n鉴权 / 限流 / 签名 / SSE / 对外契约"]
    Control["医梦医疗智能体应用控制层\n路由 / TaskState / Card / File / Meter / Audit"]
    Adapter["FastGPT Adapter\n输入裁剪 / API 调用 / SSE 归一 / 输出校验"]
    FastGPT["FastGPT AI 能力层\nLLM / Workflow / RAG / OCR / MCP Client"]
    Mcp["医梦 MCP Gateway\nHIS / LIS / EMR / PACS / 支付 / 叫号适配"]
    Hospital["医院业务系统\nHIS / LIS / EMR / PACS / 支付 / 叫号 / 物联平台"]

    Entry --> Open
    Open --> Control
    Control --> Adapter
    Adapter --> FastGPT
    Control --> Mcp
    FastGPT -.仅允许调用.-> Mcp
    Mcp --> Hospital
```

### 6.2 正确职责划分

| 层级 | 归属 | 职责 |
| --- | --- | --- |
| 外部入口 | emoon / 医院入口接 emoon | 用户入口、终端入口、医生端入口 |
| OpenPlatform | emoon | 鉴权、签名、SSE、幂等、traceId、对外接口 |
| 医疗控制层 | emoon | 场景、任务、卡片、文件、工具、计量、审计 |
| FastGPT Adapter | emoon | 适配 FastGPT API，控制输入输出 |
| AI 能力层 | FastGPT / 深信服 | Workflow、RAG、OCR、模型调用 |
| 医院系统层 | 医院 / 厂商，经 emoon 接入 | HIS、LIS、EMR、支付、叫号等 |

### 6.3 禁止事项

以下行为禁止：

- 终端、医生端、患者端直接调用 FastGPT；
- FastGPT 直接调用 HIS / LIS / EMR / PACS / 支付 / 叫号；
- FastGPT 直接持有医院系统密钥；
- FastGPT Workflow 直接执行挂号、支付、签到、写 EMR 等高风险动作；
- 将医疗主状态只保存在 FastGPT；
- 将完整病历、身份证、舌象原图等敏感数据无控制地传给 FastGPT；
- 用 FastGPT 默认 `usage` 直接扣费；
- 在 `emoon-openplatform` 新增 FastGPT 业务实现逻辑。

### 6.4 emoon-backend 内部系统与 FastGPT 调用关系

FastGPT 在 emoon-backend 中只有一个直接调用入口：

```text
emoon-ai-agent / FastGPT Adapter
```

其他模块通过 emoon 内部 API、Facade、领域服务与 `emoon-ai-agent` 协作，不直接调用 FastGPT。

```mermaid
flowchart LR
    subgraph Entry["入口模块"]
        Open["emoon-openplatform\nOpenAPI / SSE / 鉴权 / 幂等"]
        Admin["emoon-admin\n管理后台入口"]
    end

    subgraph Api["API 契约层"]
        AgentApi["emoon-ai-agent-api\nAgentRequest / AgentResponse"]
        CardApi["emoon-ai-card-api"]
        DeviceApi["emoon-ai-device-api"]
        FileApi["emoon-ai-file-api"]
        MeterApi["emoon-ai-meter-api"]
        McpApi["emoon-ai-mcp-api"]
        SystemApi["emoon-system-api\nAiAgentEngineConfig"]
    end

    subgraph Domain["医梦 AI 领域实现层"]
        Agent["emoon-ai-agent\nAgentRouter / TaskState / FastGptAgentEngine"]
        FastAdapter["FastGPT Adapter\n输入裁剪 / SSE 归一 / 输出校验 / Usage 提取"]
        Card["emoon-ai-card\nCard Runtime / Card Action"]
        Device["emoon-ai-device\nDevice Registry / Scene Profile"]
        File["emoon-ai-file\n文件元数据 / 短期 URL / 审计"]
        Meter["emoon-ai-meter\nMeterEvent / Usage 归集"]
        Billing["emoon-ai-billing\n账单 / 能力值"]
        Audit["审计日志\ntraceId / 输入输出摘要"]
        Mcp["emoon-ai-mcp\nMCP Gateway / HIS Adapter"]
        System["emoon-system\n引擎配置 / 管理后台 CRUD"]
    end

    FastGPT["FastGPT\nWorkflow / RAG / OCR / LLM / MCP Client"]
    Hospital["医院系统\nHIS / LIS / EMR / PACS / 支付 / 叫号 / 物联"]

    Open --> AgentApi --> Agent
    Admin --> SystemApi --> System
    System --> Agent
    Agent --> FastAdapter --> FastGPT
    Agent --> CardApi --> Card
    Agent --> DeviceApi --> Device
    Agent --> FileApi --> File
    Agent --> MeterApi --> Meter
    Meter --> Billing
    Agent --> Audit
    Card --> McpApi --> Mcp
    FastGPT -.仅允许工具调用.-> Mcp
    Mcp --> Hospital
    File -.短期受控 URL / 脱敏摘要.-> FastAdapter
    FastAdapter -.节点 usage / responseData.-> Meter
```

调用顺序按一次终端对话请求拆解如下：

| 顺序 | 发起方 | 接收方 | 调用内容 | 说明 |
| --- | --- | --- | --- | --- |
| 1 | 终端 / 医生端 / 患者端 | `emoon-openplatform` | `/agent/chat/stream` 等 P0 接口 | 外部只接 emoon，不接 FastGPT |
| 2 | `emoon-openplatform` | `emoon-ai-agent-api` | 统一 Agent 命令 | 入口层只做鉴权、签名、SSE、幂等 |
| 3 | `emoon-ai-agent` | `emoon-ai-device` | 查询设备场景和允许能力 | 限定 allowedAgents / allowedCards |
| 4 | `emoon-ai-agent` | `emoon-ai-file` | 获取短期文件 URL 或脱敏摘要 | FastGPT 不接收文件事实源 |
| 5 | `emoon-ai-agent` | `FastGPT Adapter` | 组装 FastGPT 请求 | 裁剪输入，注入 traceId、任务、动线、设备上下文 |
| 6 | `FastGPT Adapter` | FastGPT | `/api/v1/chat/completions` | 唯一直接调用 FastGPT 的运行链路 |
| 7 | FastGPT | `emoon-ai-mcp` | MCP 工具调用，可选 | 只能调用 emoon MCP Gateway |
| 8 | `emoon-ai-mcp` | 医院系统 | HIS/LIS/EMR/PACS/支付/叫号适配 | 医院系统不感知 FastGPT |
| 9 | FastGPT | `FastGPT Adapter` | SSE / JSON / responseData | Adapter 做输出校验和 usage 提取 |
| 10 | `emoon-ai-agent` | `emoon-ai-card` | 创建卡片实例 | FastGPT 只返回卡片建议 |
| 11 | `emoon-ai-agent` | `emoon-ai-meter` / Audit | 写计量事件和审计摘要 | 不使用 FastGPT 默认 usage 直接扣费 |
| 12 | `emoon-openplatform` | 外部终端 | `message_delta` / `card_created` / `completed` | 对外事件格式保持 emoon 稳定契约 |

各内部系统与 FastGPT 的关系：

| emoon 内部系统 | 是否直接调用 FastGPT | 与 FastGPT 的关系 | 关键注意事项 |
| --- | --- | --- | --- |
| `emoon-openplatform` | 否 | 入口层通过 Agent API 间接触发 | 不写 FastGPT HTTP 客户端，不保存 FastGPT 业务状态 |
| `emoon-admin` | 否 | 管理后台配置引擎、Agent、知识库映射 | 只调用 emoon 管理服务，不绕过领域层 |
| `emoon-system` | 有限 | 可做 FastGPT 配置校验、App/版本元数据读取 | 只做管理面，不进入运行主链路 |
| `emoon-ai-agent` | 是 | 唯一运行时直接调用 FastGPT 的领域模块 | 放置 `FastGptAgentEngine`、输出归一、usage 提取 |
| `emoon-ai-card` | 否 | 消费 FastGPT 归一后的卡片建议 | 卡片实例和动作状态仍在 emoon |
| `emoon-ai-device` | 否 | 提供设备和场景上下文给 Agent | 不把设备配置同步给 FastGPT 做事实源 |
| `emoon-ai-file` | 否 | 提供短期 URL 或脱敏摘要 | 医疗敏感文件事实源在 emoon |
| `emoon-ai-mcp` | 被 FastGPT 间接调用 | 作为 FastGPT MCP Client 唯一可连工具网关 | 工具风险分级、鉴权、幂等、审计必须在此层 |
| `emoon-ai-meter` | 否 | 消费 FastGPT 节点用量和 emoon 调用事件 | 默认 usage 不可信，账本以 emoon 归集为准 |
| `emoon-ai-billing` | 否 | 基于 Meter 事件生成账单 | 不读取 FastGPT 账单作为事实源 |
| `emoon-ai-operation` | 否 | 运营统计可引用 FastGPT 日志摘要 | 指标口径以 emoon 事件为准 |

## 7. 模块级接入设计

### 7.1 模块归属

遵循 `AI中台工程约束.md`：

| 能力 | 落位模块 | 说明 |
| --- | --- | --- |
| FastGPT 对话引擎 | `emoon-ai-agent` | 新增 `FastGptAgentEngine` |
| FastGPT 输出归一 | `emoon-ai-agent` | 新增 `FastGptOutputNormalizer` |
| FastGPT 知识库运行副本 | `emoon-ai-agent` 或后续独立知识库适配 | 新增 `FastGptKnowledgeEngine` |
| FastGPT 配置管理 | `emoon-system` + API 契约 | 扩展 `AiAgentEngineConfig` 语义 |
| Card Runtime | `emoon-ai-card` | 不放到 FastGPT |
| MCP Gateway | `emoon-ai-mcp` | 医院系统唯一工具网关 |
| 文件事实源 | `emoon-ai-file` | 敏感文件先入 emoon |
| 计量账本 | `emoon-ai-meter` / `billing` | 不信任 FastGPT 默认 usage |
| 对外入口 | `emoon-openplatform` | 只做入口适配，不写 FastGPT 业务逻辑 |

### 7.2 新增 `engineType=fastgpt`

`ai_agent_engine_config.engine_type` 增加：

```text
fastgpt
```

建议配置结构：

```json
{
  "baseUrl": "http://fastgpt:3000",
  "apiKey": "fastgpt-xxxx",
  "appId": "fastgpt-app-id",
  "detailMode": "metering",
  "timeout": {
    "connectMs": 10000,
    "readMs": 120000,
    "sseIdleMs": 300000
  },
  "fallbackPolicy": {
    "onTimeout": "preset_reply",
    "onError": "preset_reply",
    "presetReply": "AI 服务暂时不可用，请稍后再试"
  },
  "outputSchemaVersion": "emoon-card-output-v1"
}
```

字段说明：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `baseUrl` | 是 | FastGPT 服务地址，不含末尾 `/` |
| `apiKey` | 是 | FastGPT 应用级 API Key |
| `appId` | 建议 | 用于 emoon 侧映射和审计；实际调用可能由 API Key 鉴权决定 |
| `detailMode` | 是 | `off` / `debug` / `metering`，控制是否请求 `detail=true` |
| `timeout` | 是 | 连接、读取、SSE 空闲超时 |
| `fallbackPolicy` | 是 | 超时或异常时的降级策略 |
| `outputSchemaVersion` | 是 | FastGPT 输出必须满足的 emoon Schema |

### 7.3 `FastGptAgentEngine`

新增实现：

```text
emoon-infra/emoon-modules/emoon-ai/emoon-ai-agent
└── src/main/java/com/emoon/ai/agent/infrastructure/fastgpt/
    ├── FastGptAgentEngine.java
    ├── FastGptApiClient.java
    ├── FastGptEngineConfig.java
    ├── FastGptOutputNormalizer.java
    └── FastGptUsageExtractor.java
```

职责：

- 实现 `AgentEngine`；
- `getEngineType()` 返回 `fastgpt`；
- 同步对话调用 `/api/v1/chat/completions`；
- 流式对话解析 FastGPT SSE；
- `AgentRequest.inputs` 映射到 FastGPT `variables`；
- `conversationId` 映射到 FastGPT `chatId`；
- 将 FastGPT 输出归一成 `AgentResponse`；
- 将节点用量写入 metadata，供计量层消费。

不要做：

- 不在 Engine 内创建卡片实例；
- 不在 Engine 内直接调 MCP；
- 不在 Engine 内写计量账本；
- 不在 Engine 内操作 HIS；
- 不把 FastGPT 原始异常直接暴露给终端。

### 7.4 请求映射

`AgentRequest` 到 FastGPT 请求映射：

| `AgentRequest` | FastGPT 字段 | 说明 |
| --- | --- | --- |
| `agentId` | metadata / variables | 用于追踪，不直接依赖 `model` |
| `conversationId` | `chatId` | emoon 会话 ID 或外部映射 ID |
| `query` | `messages[-1].content` | 用户输入 |
| `userId` | `customUid` / variables | 视 FastGPT 鉴权方式决定 |
| `inputs` | `variables` | 场景、设备、任务、动线、traceId 等 |
| `files` | message content 中的 `image_url` / `file_url` | 只能传 emoon File Service 生成的受控 URL |

示例请求：

```json
{
  "chatId": "conv_20260613_0001",
  "stream": true,
  "detail": true,
  "responseChatItemId": "msg_20260613_0001",
  "variables": {
    "traceId": "trace_20260613_0001",
    "projectId": "1",
    "deviceType": "kiosk",
    "sceneCode": "OUTPATIENT_TRIAGE",
    "taskType": "TRIAGE",
    "journeyStage": "WAITING_CHECKIN"
  },
  "messages": [
    {
      "role": "user",
      "content": "我头疼、发烧，应该挂什么科？"
    }
  ]
}
```

### 7.5 输出 Schema

FastGPT Workflow 最终输出必须满足 emoon 输出 Schema。建议 P0 使用：

```json
{
  "reply": "建议您优先挂发热门诊或全科门诊，由医生进一步判断。",
  "cards": [
    {
      "cardKey": "department-selection",
      "cardData": {
        "departments": [
          {
            "deptId": "dept_fever",
            "name": "发热门诊",
            "reason": "存在发热症状"
          }
        ]
      }
    }
  ],
  "riskLevel": "MEDICAL_ADVICE",
  "scenarioCode": "OUTPATIENT_TRIAGE"
}
```

归一化规则：

- 如果输出是纯文本，全部作为 `reply`；
- 如果输出是 JSON，必须校验 `reply/cards/riskLevel/scenarioCode`；
- `cardKey` 必须在 emoon 卡片定义中存在；
- `cardData` 必须通过卡片 Schema 校验；
- `riskLevel` 为高风险时，必须触发人工确认或降级；
- 输出中不得包含未脱敏身份证、手机号、完整病历原文、接口密钥。

## 8. 数据、文件与隐私设计

### 8.1 数据最小化

FastGPT 只接收完成当前 AI 子任务所需的最小上下文。

错误示例：

```json
{
  "patientName": "张三",
  "idCard": "4403...",
  "phone": "138...",
  "fullEmrText": "完整病历原文..."
}
```

正确示例：

```json
{
  "age": 45,
  "gender": "FEMALE",
  "chiefComplaint": "头痛伴发热 1 天",
  "abnormalItems": [
    {
      "code": "WBC",
      "name": "白细胞计数",
      "value": "12.3",
      "flag": "HIGH"
    }
  ]
}
```

### 8.2 文件处理原则

所有医疗敏感文件必须先进入 emoon File Service。

```text
终端 / 医生端 / 患者端
        ↓
emoon /files/upload
        ↓
emoon 文件元数据、审计、脱敏、访问控制
        ↓
短期受控 URL 或脱敏摘要
        ↓
FastGPT
```

原因：

- 文件上传需要幂等；
- 文件删除需要审计；
- 舌象、面诊、报告、身份证等属于敏感数据；
- FastGPT 不能成为文件源资产；
- 后续医生反馈和知识库更新需要引用 emoon 文件 ID。

### 8.3 FastGPT 文件 URL 注意事项

FastGPT 对话文档示例支持 `image_url` 和 `file_url`，但这不代表可以直接传长期公网 URL。

要求：

- URL 必须短期有效；
- URL 必须可审计；
- URL 不应暴露真实 OSS bucket 结构；
- URL 不应包含永久 token；
- URL 最好绑定 traceId / fileId / projectId；
- 高敏文件应优先传结构化摘要，不传原文件。

## 9. 知识库设计

### 9.1 源资产与运行副本

医梦知识库分两层：

| 层级 | 事实源 | 职责 |
| --- | --- | --- |
| 知识库源资产 | emoon | 原始文件、医生反馈、审核状态、版本、发布记录 |
| 知识库运行副本 | FastGPT | 向量化、RAG 检索、Workflow 引用 |

原则：

```text
医生反馈不能直接写入 FastGPT 知识库。
必须先进入 emoon 审核，再同步到 FastGPT 运行副本。
```

### 9.2 新增 `FastGptKnowledgeEngine`

当前已有 `DifyKnowledgeEngine`，FastGPT 接入需要新增：

- list datasets；
- get dataset；
- create dataset；
- update dataset；
- upload document；
- update document；
- delete document；
- list segments；
- create / update / delete segments；
- retrieve / searchTest；
- indexing status。

### 9.3 迁移策略

不要一次性把所有知识库从 Dify 迁移到 FastGPT。

建议步骤：

1. 选一个非生产知识库验证创建、上传、检索；
2. 建立 emoon 本地知识库 ID 与 FastGPT datasetId 的映射；
3. 只同步已审核文档；
4. 验证同一问题在 Dify 和 FastGPT 中的检索效果；
5. 再切换单个 Agent 的知识库运行副本；
6. 保留 Dify 副本一段时间，支持回退。

## 10. MCP 与医院系统设计

### 10.1 总原则

你的总体设计思路是合理的，并且应作为本文档的正式边界：

```text
FastGPT 负责“AI 怎么调用工具”。
医梦负责“工具到底是什么、能不能调、调哪些数据、是否需要医生确认、调用结果如何进入医疗业务闭环”。
```

FastGPT 的 MCP 能力是优势，但必须被医梦约束。无论深信服交付的 FastGPT 版本是否包含完整 MCP Server 构建能力，医院系统都不能直接暴露给 FastGPT。医梦必须统一对接各家医院，把 HIS、LIS、EMR、PACS、慢病平台、物联平台、支付、叫号等系统封装成标准化、可鉴权、可审计、可限流、可脱敏、可幂等的医疗工具 API。

允许：

```text
FastGPT Workflow / Agent
        ↓
FastGPT MCP ToolSet / HTTP ToolSet
        ↓
emoon MCP Gateway / Tool Server
        ↓
HIS / LIS / EMR / PACS / 慢病平台 / 物联平台 / 支付 / 叫号
```

禁止：

```text
FastGPT → HIS / LIS / EMR / PACS
FastGPT → 支付 / 挂号 / 叫号原始接口
FastGPT → 设备平台原始接口
```

### 10.2 FastGPT 当前 MCP 能力

基于本地源码 `/Users/destiny/dev/emoon/projects/FastGPT`，当前 FastGPT MCP 能力需要分成两类理解。

| 能力 | 本地源码证据 | 作用 | 对医梦的意义 | 是否进入 P0 |
| --- | --- | --- | --- | --- |
| MCP Client / MCP ToolSet | `packages/service/core/app/mcp.ts`、`/api/core/app/mcpTools/*` | FastGPT 作为 MCP Client 连接外部 MCP Server，执行 `listTools` 和 `callTool` | 可把 emoon MCP Gateway 注册成 FastGPT 工具集，让 Workflow/Agent 调用受控医疗工具 | 是，作为工具调用主方案 |
| Streamable HTTP + SSE 兼容 | `MCPClient` 先尝试 `StreamableHTTPClientTransport`，失败后回退 `SSEClientTransport` | 支持两类 MCP 传输方式 | emoon MCP Gateway 应优先实现 Streamable HTTP，同时可提供 SSE 兼容端点 | 是，联调需验证 |
| 工具列表读取 | `/api/core/app/mcpTools/getTools` | 按 URL 和 headerSecret 拉取远端 MCP 工具 schema | emoon 可用于注册前校验 FastGPT 看到的工具是否被裁剪 | 是，P1 |
| MCP ToolSet 创建/更新 | `/api/core/app/mcpTools/create`、`/api/core/app/mcpTools/update` | 在 FastGPT 内创建或更新 MCP ToolSet 应用 | emoon 管理后台可受控注册项目级工具集 | 是，P1 |
| MCP 工具试运行 | `/api/core/app/mcpTools/runTool` | 直接通过 FastGPT 调用远端 MCP 工具 | 只适合联调验收，不应成为生产业务调用入口 | 否，生产不走 |
| Workflow/Agent 工具调用 | `dispatch/child/runTool.ts`、`dispatch/ai/agent/sub/tool/*` | FastGPT Workflow/Agent 在运行中调用已绑定 MCP 工具 | AI 编排层可决定何时调用工具，但不能绕过 emoon 权限 | 是 |
| 私网地址防护 | `assertMCPUrlNotInternal(url)` | 阻止 MCP URL 指向内网地址 | emoon Gateway 需要提供 FastGPT 可访问且受控的域名，或由部署方案明确放行代理 | 是，部署风险 |
| FastGPT MCP Server | `/api/support/mcp/*`、`/api/mcp/app/[key]/mcp` | 把 FastGPT 应用包装成 MCP Server，对外暴露为工具 | 可供 emoon 或内部平台调用 FastGPT 应用，但不能替代医疗工具网关 | 否，P2 |
| MCP Server 绑定限制 | `McpAppsBodySchema` 最多 50 个应用，创建端限制每团队最多 100 个 MCP 服务 | 限制 FastGPT 对外暴露工具规模 | 不适合承载医院全量工具目录 | 否，P2 |

结论：

- FastGPT 具备“调用外部 MCP Server”的能力，这正好适合调用 emoon MCP Gateway。
- FastGPT 也具备“把自身应用暴露成 MCP Server”的能力，但它暴露的是 FastGPT 应用，不是医院业务系统适配层。
- 医疗工具 API 的定义、授权、脱敏、幂等、审计、确认和业务闭环必须在医梦完成。
- 如果深信服交付版本裁剪掉 MCP ToolSet，则医梦仍提供 Tool Server，FastGPT 通过 HTTP ToolSet 调用；如果连 HTTP ToolSet 也不可用，则工具动作退化为 FastGPT 输出结构化意图，由 emoon Card Runtime 执行。

### 10.3 推荐架构

```mermaid
flowchart TD
    Doctor["医生端 / 患者端 / 终端设备"] --> Open["emoon-openplatform\n统一入口 / 鉴权 / SSE"]
    Open --> Control["医疗智能体应用控制层\n场景路由 / 会话 / 卡片 / 任务状态"]
    Control --> Adapter["FastGPT Adapter\nengineType=fastgpt"]
    Adapter --> FastGPT["FastGPT\nAgent / Workflow / RAG / MCP ToolSet"]

    FastGPT -->|"listTools / callTool\n只允许访问受控地址"| Mcp["emoon MCP Gateway / Tool Server\n工具目录 / 鉴权 / 脱敏 / 限流 / 审计 / 幂等"]
    Mcp --> His["HIS"]
    Mcp --> Lis["LIS"]
    Mcp --> Emr["EMR"]
    Mcp --> Pacs["PACS"]
    Mcp --> Chronic["慢病平台"]
    Mcp --> Iot["物联平台"]
    Mcp --> Pay["支付 / 叫号"]

    FastGPT -.禁止.-> His
    FastGPT -.禁止.-> Lis
    FastGPT -.禁止.-> Emr
    FastGPT -.禁止.-> Iot

    Mcp --> Audit["emoon Audit / Meter / Tool Ledger"]
    Mcp --> Card["Card Runtime\n人工确认 / 业务闭环"]
```

这张图表达三个事实：

1. FastGPT 可以编排工具，但不能拥有医院接口主权。
2. 医梦 MCP Gateway 是医院系统唯一可达的 AI 工具网关。
3. L3 以上写动作必须回到 Card Runtime 或医生确认流程，不能由模型直接提交。

### 10.4 三种交付模式

| 模式 | 前提 | 调用方式 | 医梦职责 | FastGPT 职责 | 适用优先级 |
| --- | --- | --- | --- | --- | --- |
| A. FastGPT MCP ToolSet 主方案 | 深信服交付版本保留 `/core/app/mcpTools/*` 和 Workflow MCP 工具调用 | FastGPT MCP Client → emoon MCP Gateway | 提供 MCP Server、工具目录、权限、审计、脱敏、幂等、确认策略 | 注册 MCP ToolSet，在 Workflow/Agent 中选择工具 | P0/P1 主方案 |
| B. HTTP ToolSet 兜底 | FastGPT 无 MCP ToolSet，但保留 HTTP ToolSet | FastGPT HTTP ToolSet → emoon Tool Server REST API | 提供 REST Tool Server，接口能力与 MCP 工具一致 | 在 Workflow 中配置 HTTP 工具调用 | P1 兜底 |
| C. 结构化意图兜底 | FastGPT 无 MCP/HTTP 工具能力或医院环境不允许 FastGPT 主动访问工具 | FastGPT 输出 JSON 意图 → emoon 解析 → Card Action/Tool Executor | 执行全部工具动作和闭环 | 只生成建议、参数和解释 | P0 安全兜底 |

公司评审应以 A 为目标、B 为技术兜底、C 为安全兜底。不能因为 FastGPT 支持 MCP，就把医院接口直接交给 FastGPT 配置。

### 10.5 医梦 MCP Gateway 职责

emoon MCP Gateway 需要提供：

| 能力 | 说明 |
| --- | --- |
| 工具目录 | 按租户、医院、项目、科室、设备、Agent 场景返回可见工具 |
| 工具 schema | 为 FastGPT 提供稳定的 inputSchema、description、枚举、必填项、示例 |
| 鉴权 | 校验 FastGPT Adapter 签发的 token、租户、项目、Agent、会话、设备、医生或患者身份 |
| 授权 | 决定当前场景能否看到工具、能否调用工具、是否需要人工确认 |
| 限流 | 按租户、项目、工具、设备、会话限流，防止模型循环调用 |
| 脱敏 | 请求进入医院系统前做最小化，响应返回 FastGPT 前去除非必要敏感字段 |
| 幂等 | 对写动作要求 `idempotencyKey`，防重复签到、重复挂号、重复支付 |
| 审计 | 记录 traceId、requestId、conversationId、agentVersion、toolName、参数摘要、结果摘要、耗时、调用人、确认人 |
| 错误归一 | 把 HIS/LIS/EMR/PACS 等异构错误转成统一错误码和可解释文本 |
| 降级 | 医院系统不可用时返回可恢复错误，不让 FastGPT 编造结果 |
| 确认编排 | 对 L3 以上动作返回 `requiresConfirmation=true`，交由 Card Runtime 创建确认卡片 |

MCP Gateway 的工具命名建议使用稳定业务语义，不暴露医院厂商或表结构：

```text
hospital.schedule.search
hospital.queue.status.get
patient.report.summary.get
patient.emr.summary.get
appointment.intent.prepare
appointment.confirmed.create
device.vital.latest.get
chronic.followup.plan.suggest
```

### 10.6 工具风险分级

| 风险等级 | 示例 | FastGPT 是否可直接调用 | 控制方式 |
| --- | --- | --- | --- |
| L0 公共查询 | 科室介绍、楼层位置 | 可通过 emoon Gateway | 审计 + 限流 |
| L1 普通业务查询 | 排班、候诊状态 | 可通过 emoon Gateway | 项目授权 + 脱敏 |
| L2 敏感查询 | 报告、病历摘要 | 谨慎开放 | 身份授权 + 最小化 |
| L3 业务写入 | 签到、锁号、挂号 | 不允许模型直接执行 | Card Action 人工确认 |
| L4 财务动作 | 支付、退款 | P0 不开放 | 专项风控 |
| L5 医疗正式写入 | EMR、处方、诊断 | 不开放自动写 | 医生确认 + 审计 |

补充约束：

- L0/L1 可以让 FastGPT 在 Workflow 中直接调用，但结果仍要进入 emoon 审计。
- L2 必须最小化返回，优先返回摘要、结论、引用 ID，不返回完整病历或完整报告原文。
- L3 不能由模型直接完成，FastGPT 最多生成“待确认动作建议”，由 Card Runtime 创建确认卡片。
- L4/L5 默认不开放；确需开放时必须单独 ADR、安全评审、医院书面确认和专项风控。

### 10.7 FastGPT MCP 配置规则

FastGPT 侧只能注册医梦提供的 MCP/Tool 地址：

```text
允许：
https://ai-gateway.{hospital-domain}/mcp/{tenant}/{project}
https://ai-gateway.{hospital-domain}/tools/http/{tenant}/{project}

禁止：
http://his.internal.local
http://lis.xxx.hospital
http://emr-service:8080
http://device-platform.private
```

配置要求：

| 配置项 | 要求 |
| --- | --- |
| URL | 只能是 emoon MCP Gateway 或 emoon Tool Server 的受控域名；如果 FastGPT 私网地址防护阻断，需要通过受控公网/专线代理解决，不允许关闭边界控制后直连 HIS |
| Header Secret | 由 emoon 管理后台生成短期或可轮换 token，不能手工散落在 FastGPT 多个应用中 |
| ToolList | 由 emoon 生成项目级裁剪结果，再写入 FastGPT MCP ToolSet |
| Workflow 使用 | FastGPT Workflow 可以选择工具，但不能新增未授权工具 |
| 版本映射 | MCP ToolSet 配置必须纳入 emoon agentVersion / FastGPT appVersion 映射 |
| 漂移检测 | 定期比对 FastGPT ToolSet 中的 URL、toolName、schema 与 emoon 发布快照 |

### 10.8 标准调用流程

查询类工具：

```mermaid
sequenceDiagram
    participant FG as FastGPT Workflow
    participant MCP as emoon MCP Gateway
    participant Auth as emoon Auth/Policy
    participant HIS as Hospital System
    participant Audit as Audit/Meter

    FG->>MCP: callTool(toolName, params, trace headers)
    MCP->>Auth: 校验租户/项目/Agent/会话/身份/工具风险
    Auth-->>MCP: allow + dataScope
    MCP->>HIS: 调用医院系统适配器
    HIS-->>MCP: 原始结果
    MCP->>MCP: 脱敏 / 摘要 / 错误归一
    MCP->>Audit: 写工具调用审计
    MCP-->>FG: 返回受控结果
```

写入类工具：

```mermaid
sequenceDiagram
    participant FG as FastGPT Workflow
    participant MCP as emoon MCP Gateway
    participant Card as Card Runtime
    participant User as 医生/患者
    participant HIS as Hospital System
    participant Audit as Audit/Meter

    FG->>MCP: callTool(appointment.intent.prepare, params)
    MCP-->>FG: requiresConfirmation=true + cardSuggestion
    FG-->>Card: 输出卡片建议
    Card->>User: 展示确认卡片
    User->>Card: 确认
    Card->>MCP: confirmed action + idempotencyKey
    MCP->>HIS: 执行业务写入
    HIS-->>MCP: 写入结果
    MCP->>Audit: 写确认人、幂等键、结果
    MCP-->>Card: 业务闭环结果
```

### 10.9 医梦 MCP 工具 API 契约

所有医疗工具都必须具备统一元数据：

| 字段 | 说明 |
| --- | --- |
| `toolName` | 稳定工具名，例如 `hospital.queue.status.get` |
| `riskLevel` | L0-L5 风险等级 |
| `tenantId/projectId/hospitalId` | 多租户和医院边界 |
| `agentId/agentVersion` | AI 应用版本 |
| `conversationId/requestId/traceId` | 全链路追踪 |
| `operatorType/operatorId` | 医生、患者、设备、系统任务 |
| `idempotencyKey` | L3 以上写动作必填 |
| `dataScope` | 数据授权范围 |
| `requiresConfirmation` | 是否需要卡片确认 |
| `expiresAt` | 工具调用上下文过期时间 |

工具返回值必须避免把医院原始响应直接交给模型：

```json
{
  "success": true,
  "toolName": "patient.report.summary.get",
  "riskLevel": "L2",
  "traceId": "trace-xxx",
  "data": {
    "summary": "血常规提示白细胞略高，需结合症状判断。",
    "references": [
      {
        "type": "report",
        "refId": "report-123",
        "displayName": "血常规",
        "sensitive": false
      }
    ]
  },
  "requiresConfirmation": false,
  "auditId": "audit-xxx"
}
```

### 10.10 FastGPT MCP Server 能力的边界

FastGPT 的 `/support/mcp/*` 和 `/mcp/app/[key]/mcp` 可以把 FastGPT 应用包装成 MCP Server。这个能力的定位是：

- 让 emoon 或内部平台把某个 FastGPT 应用当作 AI 工具调用；
- 让多个 FastGPT 应用之间复用“AI 应用工具”；
- 为非医疗生产链路提供 AI 能力封装。

它不能承担：

- 医院 HIS/LIS/EMR/PACS 的统一适配；
- 医疗工具的最终鉴权和审计；
- 医生确认和业务写入闭环；
- 多医院接口差异治理；
- 医疗数据脱敏与最小化授权。

因此，即使 FastGPT 有 MCP Server 构建能力，医梦仍要建设 MCP Gateway / Tool Server。FastGPT MCP Server 只作为“AI 应用对外工具化”的可选能力，不作为“医院工具网关”的实现。

## 11. 卡片与任务状态设计

### 11.1 FastGPT 不创建卡片实例

FastGPT 只返回卡片建议：

```json
{
  "cardKey": "department-selection",
  "cardData": {
    "departments": []
  }
}
```

真正创建卡片实例的是 emoon Card Runtime：

```text
FastGPT 输出卡片建议
        ↓
FastGPTOutputNormalizer 校验
        ↓
Card Runtime 创建 ai_card_instance
        ↓
OpenPlatform SSE 发送 card_created
        ↓
终端执行 Card Action
        ↓
emoon 执行业务动作
```

### 11.2 FastGPT 不维护医疗主状态

医疗任务状态保存在 emoon：

- `conversationId`；
- `taskId`；
- `taskType`；
- `currentStep`；
- `journeyState`；
- `cardInstanceId`；
- `traceId`；
- `toolInvokeId`；
- `auditId`。

FastGPT 可辅助判断下一步，但不能成为状态事实源。

## 12. 计量、账本与审计设计

### 12.1 不能信任默认 usage

FastGPT v1 响应 Schema 中 `usage` 可能固定为：

```json
{
  "prompt_tokens": 1,
  "completion_tokens": 1,
  "total_tokens": 1
}
```

这只是占位值，不能进入能力值扣费。

### 12.2 FastGPT 用量归集策略

P0 建议：

- 对需要计量的请求设置 `detail=true`；
- 从 `responseData` 中提取各节点 `tokens`、`price`、`model`、`moduleName`；
- 归一成 emoon `MeterEvent`；
- 同时记录 FastGPT 原始 `responseData` 摘要，便于排障；
- 计费仍由 emoon 账本决定。

P1 增强：

- 对接 FastGPT 应用日志或模型日志；
- 建立 traceId 对账；
- 增加差异告警；
- 形成项目、设备、智能体、场景维度统计。

### 12.3 审计字段

每次 FastGPT 调用至少记录：

| 字段 | 说明 |
| --- | --- |
| `traceId` | 全链路追踪 ID |
| `projectId` | 项目 |
| `tenantId` | 租户 |
| `agentId` | emoon 智能体 ID |
| `engineType` | `fastgpt` |
| `fastgptAppId` | FastGPT 应用 ID |
| `fastgptVersionId` | FastGPT 版本 ID |
| `conversationId` | emoon 会话 ID |
| `fastgptChatId` | FastGPT chatId |
| `messageId` | emoon 消息 ID |
| `fastgptResponseItemId` | FastGPT 响应 ID |
| `inputSummary` | 脱敏输入摘要 |
| `outputSummary` | 脱敏输出摘要 |
| `usageDetail` | 节点用量摘要 |
| `errorCode` | 错误码 |
| `durationMs` | 耗时 |

## 13. 版本、灰度与回滚

### 13.1 版本事实源

FastGPT 有版本能力，但 emoon 必须维护医疗场景发布事实。

建议新增或扩展映射数据：

```text
agentId
engineType
fastgptAppId
fastgptVersionId
emoonOutputSchemaVersion
snapshotJson
status
grayPolicy
publishedBy
publishedAt
rollbackFrom
```

### 13.2 发布流程

```text
1. FastGPT 中完成 Workflow 调整
2. FastGPT 发布版本
3. emoon 拉取版本详情或保存快照
4. emoon 执行测试问题集
5. 输出 Schema 校验
6. 工具权限校验
7. 计量字段校验
8. 灰度到指定项目/设备/Agent
9. 监控错误率与人工反馈
10. 全量切换或回滚
```

### 13.3 回滚策略

优先级：

1. 切回上一 FastGPT versionId；
2. 切回上一 emoon AgentEngine 配置；
3. 切回 Dify；
4. 切回 Mock / 模板回复；
5. 关闭高风险能力，只保留导诊 FAQ。

## 14. 分阶段落地计划

### 阶段 0：技术验证与商务边界确认

目标：

- 确认 FastGPT 部署版本；
- 确认社区版/商业版能力边界；
- 确认许可证和 LOGO/版权要求；
- 验证 `/api/v1/chat/completions`；
- 验证 `detail=true` 的用量字段；
- 验证 MCP 能否连接 emoon Gateway；
- 验证知识库创建、上传、检索。

交付物：

- FastGPT API 验证报告；
- 社区版/商业版能力清单；
- 接口样例；
- 风险确认表。

### 阶段 1：FastGptAgentEngine

目标：

- 新增 `engineType=fastgpt`；
- 打通同步对话；
- 打通 SSE；
- 支持 FastGPT 输出归一；
- 支持卡片建议；
- 支持基础异常降级；
- 支持连通性测试。

验收：

- `/agent/chat` 可通过 FastGPT 返回文本；
- `/agent/chat/stream` 可返回 `message_delta` 和 `completed`；
- FastGPT 返回卡片 JSON 后，emoon 创建卡片实例；
- 异常时返回统一错误，不泄露 FastGPT 内部错误。

### 阶段 2：FastGptKnowledgeEngine

目标：

- 新增 FastGPT 知识库运行副本；
- 建立 emoon 知识库 ID 与 FastGPT datasetId 映射；
- 支持文档上传和检索；
- 保持 emoon 为知识源资产。

验收：

- 指定 Agent 可引用 FastGPT 知识库；
- 同一问题可对比 Dify/FastGPT 检索效果；
- 删除或回滚不丢失 emoon 源资产。

### 阶段 3：MCP Gateway 接入

目标：

- 建设 emoon MCP Gateway / Tool Server，封装 HIS、LIS、EMR、PACS、慢病平台、物联平台、支付、叫号等医院系统；
- FastGPT MCP ToolSet 只注册 emoon MCP Gateway 或受控代理地址；
- 如果深信服交付版本不支持 MCP ToolSet，则降级为 FastGPT HTTP ToolSet 调 emoon Tool Server；
- 如果 MCP/HTTP 工具均不可用，则 FastGPT 只输出结构化工具意图，由 emoon Card Runtime / Tool Executor 执行；
- 工具目录按租户、项目、医院、设备、Agent 场景和风险等级裁剪；
- L0/L1 查询工具可跑通；
- L2 工具只返回脱敏摘要和引用 ID；
- L3 以上写工具必须通过 Card Action 和幂等键确认。

验收：

- FastGPT 不能拿到医院原始系统地址；
- FastGPT ToolSet 中只能看到 emoon 发布快照内的工具；
- 未授权工具不可见且不可调用；
- MCP ToolSet 的 URL、headerSecret、toolList 能被 emoon 巡检和漂移告警；
- L3 以上动作不能由模型直接执行；
- 工具调用有审计记录，并能关联 requestId、conversationId、agentVersion、toolName、riskLevel、operatorId、idempotencyKey。

### 阶段 4：Dify/FastGPT 并存灰度

目标：

- 同一 emoon Agent 可配置 Dify 或 FastGPT；
- 按项目、设备、场景灰度；
- 低风险场景先切；
- 保留 Dify 回退路径；
- 灰度期间并行埋点 usage、日志、版本映射和健康状态，精细计量不作为首批灰度切流的前置阻塞项。

验收：

- 导诊 FAQ、轻分诊、报告解读入口至少一个场景完成灰度；
- FastGPT 异常可切回 Dify 或模板；
- 指标包括成功率、平均耗时、卡片创建率、人工接管率、用户反馈、计量差异；
- 灰度过程不改变 emoon 会话、卡片、任务状态事实源。

### 阶段 5：计量、审计、版本与健康探活补强

目标：

- `detail=true.responseData` 用量归集；
- FastGPT 调用审计；
- 应用版本映射；
- 回滚指针；
- 健康探活；
- 错误率监控；
- 在扩大灰度范围前完成计量账本、审计报表和版本漂移告警闭环。

验收：

- 不再使用 FastGPT 默认 usage 扣费；
- 可按 traceId 回放输入、输出、卡片、工具、计量；
- 版本切换可回滚；
- FastGPT 不可用时可降级；
- FastGPT 管理后台配置漂移能够被发现、告警并进入人工复核。

### 阶段 6：公司评审、联调验收、上线准入

目标：

- 公司内评审通过；
- 商务边界确认；
- 医院联调环境验证；
- 上线准入清单完成。

验收：

- 架构边界无争议；
- P0 能力和非 P0 能力明确；
- 合同/报价不默认包含商业版能力；
- 初级工程师能按任务拆解执行。

## 15. 风险矩阵

| 编号 | 风险 | 概率 | 影响 | 等级 | 应对 |
| --- | --- | --- | --- | --- | --- |
| R1 | FastGPT usage 为占位值导致错误扣费 | 高 | 高 | 高 | P0 禁止直接用默认 usage，必须从 detail 或日志归集 |
| R2 | FastGPT 直连医院系统导致边界失控 | 中 | 高 | 高 | 只允许连接 emoon MCP Gateway，工具按风险分级 |
| R3 | 商业版能力被误认为社区版能力 | 中 | 高 | 高 | 文档、报价、验收清单中明确版本边界 |
| R4 | Dify 已有代码被直接删除导致回归 | 中 | 高 | 高 | 双引擎并存，灰度迁移 |
| R5 | FastGPT Workflow 输出格式不稳定 | 中 | 中 | 中 | OutputNormalizer + JSON Schema + 降级 |
| R6 | 文件 URL 泄露敏感数据 | 中 | 高 | 高 | File Service 生成短期受控 URL，优先传摘要 |
| R7 | MongoDB 运维经验不足 | 中 | 中 | 中 | 部署前补备份、监控、恢复演练 |
| R8 | MCP 内网地址被 FastGPT SSRF 防护阻断 | 中 | 中 | 中 | 用服务名、网关域名或明确放行策略 |
| R9 | FastGPT 版本升级 API 不兼容 | 中 | 中 | 中 | 锁版本，建立兼容测试 |
| R10 | 医疗主状态落入 FastGPT | 低 | 高 | 高 | TaskState、Card、Audit 均以 emoon 为事实源 |
| R11 | 运营人员绕过 emoon 版本映射直接修改 FastGPT 应用或 Workflow | 中 | 高 | 高 | FastGPT 管理后台只允许交付/运维角色操作；生产发布必须回写 emoon 版本映射和快照；定期比对 FastGPT versionId/snapshot 与 emoon 生效配置，发现漂移自动告警 |

## 16. 初级工程师实现指南

### 16.1 为什么不能让 FastGPT 直连 HIS

因为 HIS 调用不是普通工具调用。它涉及：

- 医院接口密钥；
- 患者身份；
- 业务状态；
- 写操作幂等；
- 审计；
- 失败补偿；
- 医疗风险；
- 商业计量。

FastGPT 只能做 AI 推理和工具编排，不能成为医院系统网关。

### 16.2 为什么不能相信 FastGPT 默认 usage

FastGPT v1 接口默认 `usage` 可能固定为 1。这个值只是 OpenAI-compatible 响应格式的占位，不代表真实 token 或成本。

正确做法：

- 开启 `detail=true`；
- 解析 `responseData`；
- 提取节点级 tokens / price / model；
- 由 emoon 计量模块归集；
- 由 emoon 账本扣费。

### 16.3 为什么文件必须先进入 emoon File Service

医疗文件属于敏感数据。emoon File Service 提供：

- 上传幂等；
- 文件元数据；
- 删除审计；
- 保留策略；
- 权限控制；
- traceId；
- 短期访问 URL；
- 后续医生反馈引用。

FastGPT 只能拿到运行所需的短期 URL 或脱敏摘要。

### 16.4 为什么卡片动作必须由 emoon 执行

卡片动作通常是确定性业务动作，例如：

- 挂号；
- 签到；
- 建档；
- 支付引导；
- 报告确认；
- 医生审核。

这些动作需要：

- 用户确认；
- 幂等键；
- 状态机；
- 审计；
- 失败处理；
- 权限校验。

FastGPT 可以建议创建卡片，不能执行卡片动作。

### 16.5 为什么 Dify 和 FastGPT 要先并存

因为当前工程已有 Dify 代码和配置：

- 对话引擎；
- 知识库引擎；
- 意图识别；
- 管理后台连通性；
- OpenPlatform 历史客户端；
- 知识库 Controller 硬编码。

直接删除 Dify 会造成不可控回归。正确做法是：

```text
新增 fastgpt → 小场景验证 → 灰度切换 → 保留回滚 → 稳定后再清理旧链路
```

## 17. 公司评审问题清单

评审前需要明确以下问题。

### 17.1 商务与合作边界

- 深信服提供的是 FastGPT 平台、模型、算力和运维，还是还包括医疗场景实施？
- 社区版、商业版、云服务版分别进入报价的哪些部分？
- 是否允许私有化商用？
- 多租户 SaaS 场景是否需要 FastGPT 商业授权？
- FastGPT 控制台 LOGO 和版权信息是否能保留或修改？

### 17.2 产品与交付范围

- P0 是否只承诺对话、SSE、卡片输出和基础 RAG？
- 图片知识库、Web 同步、应用评测、内容审核是否属于 P1/P2？
- 医生端反馈闭环是否由 emoon 完整承接？
- FastGPT 是否只作为运行副本，不保存医梦知识源资产？

### 17.3 技术与安全边界

- FastGPT 是否部署在医院内网、深信服环境还是医梦环境？
- FastGPT 如何访问 emoon MCP Gateway？
- 是否允许 FastGPT 访问内网服务名？
- 文件 URL 有效期和访问审计如何做？
- FastGPT 日志中是否会保存敏感输入输出？

### 17.4 运维与上线

- MongoDB 谁负责备份、监控、恢复？
- FastGPT 版本谁负责升级？
- API 不兼容时谁负责修复？
- FastGPT 不可用时是否允许切回 Dify？
- 上线前是否完成压测和断线恢复测试？

## 18. 后续 ADR 建议

建议后续新增 ADR：

| ADR | 决策 |
| --- | --- |
| ADR-014 | FastGPT 作为 AIAgent 实现层接入，而非替代医梦 AI 中台 |
| ADR-015 | FastGPT Adapter 落位 `emoon-ai-agent`，OpenPlatform 不沉淀实现逻辑 |
| ADR-016 | FastGPT MCP 只能连接 emoon MCP Gateway |
| ADR-017 | FastGPT usage 不直接用于扣费，计量由 emoon 归集 |
| ADR-018 | 知识库源资产在 emoon，FastGPT 只保存运行副本 |
| ADR-019 | Dify 与 FastGPT 过渡期并存，按 Agent/项目灰度 |

## 19. 最终结论

FastGPT 接入是可行的，而且在中文生态、MCP 原生支持、私有化部署轻量化方面有优势。但公司评审必须坚持以下底线：

1. FastGPT 是 AI 能力层，不是医疗业务控制层；
2. 医梦继续掌握入口、状态、卡片、工具、文件、反馈、计量和审计；
3. 医院业务系统只接医梦 MCP Gateway；
4. 医疗敏感文件和知识源资产不交给 FastGPT 做事实源；
5. FastGPT 默认 usage 不能用于计费；
6. 社区版与商业版能力要在合同和验收中分清；
7. Dify 不立即删除，先与 FastGPT 并存灰度。

按这个边界推进，FastGPT 可以成为医梦 AI 中台的可插拔 AgentEngine，实现甲方偏好的同时，不牺牲医梦在医疗业务闭环中的核心控制权。

## 附录 A FastGPT 当前源码 API 明细

本节接口清单来自本地源码：

```text
/Users/destiny/dev/emoon/projects/FastGPT/projects/app/src/pages/api
```

说明：

- 下表按 Next.js API route 路径枚举，路径中的 `[token]`、`[key]`、`[...path]` 表示动态参数；
- 本节不展开参数和返回值，只说明主要功能、emoon 是否需要对接、当前系统环境是否需要对接；
- “emoon 是否需要对接”表示长期方案是否有接入价值；
- “当前系统环境是否需要对接”表示在现阶段 FastGPT 接入、二三期中台建设和公司评审范围内是否应进入实施计划；
- 对 FastGPT 用户、团队、外链、插件市场、初始化迁移等平台内部接口，默认不进入医梦医疗生产链路。

### A.1 对话、语音与会话

| 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
| --- | --- | --- | --- |
| `/core/chat/chatTest` | 测试对话 FastGPT 会话。 | 否，P2 | 当前不接 |
| `/core/chat/clearHistories` | 清空历史 FastGPT 会话。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/delHistory` | 删除历史 FastGPT 会话。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/feedback/adminUpdate` | 管理员更新 FastGPT 对话反馈，用于点赞、差评、管理员标记或反馈闭环。 | 可选，P1/P2 | 当前不作为事实源，只做反馈副本评估 |
| `/core/chat/feedback/closeCustom` | 关闭自定义反馈 FastGPT 对话反馈，用于点赞、差评、管理员标记或反馈闭环。 | 可选，P1/P2 | 当前不作为事实源，只做反馈副本评估 |
| `/core/chat/feedback/getFeedbackRecordIds` | 查询反馈记录 ID FastGPT 对话反馈，用于点赞、差评、管理员标记或反馈闭环。 | 可选，P1/P2 | 当前不作为事实源，只做反馈副本评估 |
| `/core/chat/feedback/updateFeedbackReadStatus` | 更新反馈已读状态 FastGPT 对话反馈，用于点赞、差评、管理员标记或反馈闭环。 | 可选，P1/P2 | 当前不作为事实源，只做反馈副本评估 |
| `/core/chat/feedback/updateUserFeedback` | 提交用户反馈 FastGPT 对话反馈，用于点赞、差评、管理员标记或反馈闭环。 | 可选，P1/P2 | 当前不作为事实源，只做反馈副本评估 |
| `/core/chat/file/presignChatFileGetUrl` | 生成对话文件读取预签名 URL FastGPT 对话侧文件临时访问。 | 谨慎，P1/P2 | 当前不直接用于医疗文件，优先 emoon File Service |
| `/core/chat/file/presignChatFilePostUrl` | 生成对话文件上传预签名 URL FastGPT 对话侧文件临时访问。 | 谨慎，P1/P2 | 当前不直接用于医疗文件，优先 emoon File Service |
| `/core/chat/getHistories` | 查询历史列表 FastGPT 会话。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/getPaginationRecords` | 分页查询记录 FastGPT 会话。 | 可选，P1 | 当前可作为排障/断线恢复储备 |
| `/core/chat/getResData` | 查询响应详情 FastGPT 会话。 | 可选，P1 | 当前可作为排障/断线恢复储备 |
| `/core/chat/helperBot/completions` | 发起对话 FastGPT 辅助机器人数据。 | 否，P2 | 当前不接 |
| `/core/chat/helperBot/deleteRecord` | 删除记录 FastGPT 辅助机器人数据。 | 否，P2 | 当前不接 |
| `/core/chat/helperBot/getFilePresign` | 获取文件预签名 FastGPT 辅助机器人数据。 | 否，P2 | 当前不接 |
| `/core/chat/helperBot/getFilePreviewUrl` | 获取文件预览 URL FastGPT 辅助机器人数据。 | 否，P2 | 当前不接 |
| `/core/chat/helperBot/getRecords` | 处理 FastGPT 辅助机器人数据。 | 否，P2 | 当前不接 |
| `/core/chat/history/batchDelete` | 批量删除 FastGPT 会话历史。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/history/clearHistories` | 清空历史 FastGPT 会话历史。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/history/delHistory` | 删除历史 FastGPT 会话历史。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/history/getHistories` | 查询历史列表 FastGPT 会话历史。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/history/getHistoryStatus` | 查询历史状态 FastGPT 会话历史。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/history/markRead` | 标记已读 FastGPT 会话历史。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/history/updateHistory` | 更新历史 FastGPT 会话历史。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/init` | 初始化 FastGPT 会话。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/inputGuide/countTotal` | 统计总数 FastGPT 输入引导。 | 否，P2 | 当前不接 |
| `/core/chat/inputGuide/create` | 创建 FastGPT 输入引导。 | 否，P2 | 当前不接 |
| `/core/chat/inputGuide/delete` | 删除 FastGPT 输入引导。 | 否，P2 | 当前不接 |
| `/core/chat/inputGuide/deleteAll` | 删除全部 FastGPT 输入引导。 | 否，P2 | 当前不接 |
| `/core/chat/inputGuide/list` | 查询列表 FastGPT 输入引导。 | 否，P2 | 当前不接 |
| `/core/chat/inputGuide/query` | 查询 FastGPT 输入引导。 | 否，P2 | 当前不接 |
| `/core/chat/inputGuide/update` | 更新 FastGPT 输入引导。 | 否，P2 | 当前不接 |
| `/core/chat/outLink/init` | 初始化 FastGPT 会话。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/recentlyUsed` | 查询最近使用 FastGPT 会话。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/record/delete` | 删除 FastGPT 对话记录、引用、响应详情或语音结果。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/record/getCollectionQuote` | 查询集合引用 FastGPT 对话记录、引用、响应详情或语音结果。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/record/getPaginationRecords` | 分页查询记录 FastGPT 对话记录、引用、响应详情或语音结果。 | 可选，P1 | 当前可作为排障/断线恢复储备 |
| `/core/chat/record/getQuote` | 查询引用 FastGPT 对话记录、引用、响应详情或语音结果。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/record/getRecords_v2` | 查询新版记录 FastGPT 对话记录、引用、响应详情或语音结果。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/record/getResData` | 查询响应详情 FastGPT 对话记录、引用、响应详情或语音结果。 | 可选，P1 | 当前可作为排障/断线恢复储备 |
| `/core/chat/record/getSpeech` | 查询语音结果 FastGPT 对话记录、引用、响应详情或语音结果。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/resume` | 恢复会话 FastGPT 会话。 | 可选，P1 | 当前可作为排障/断线恢复储备 |
| `/core/chat/team/init` | 初始化 FastGPT 会话。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/core/chat/updateHistory` | 更新历史 FastGPT 会话。 | 可选，P1 | 当前优先 emoon 会话事实源，必要时用于补偿查询 |
| `/v1/audio/transcriptions` | 执行音频转文字，面向语音输入场景。 | 可选，P2 | 当前不接，终端语音能力后置 |
| `/v1/chat/completions` | 发起 FastGPT v1 对话，触发应用编排、Workflow、RAG、模型生成和流式输出，是 emoon P0 主链路。 | 是，P0 | 当前必须规划并优先接入 |
| `/v2/chat/completions` | 发起 FastGPT v2 对话，属于新版协议候选，需在 v1 稳定后评估。 | 后续评估 | 当前不接，待 v1 稳定后评估 |
| `/v2/chat/stop` | 停止 v2 对话生成任务，用于中断长回答或异常生成。 | 后续评估 | 当前不接，待 v1 稳定后评估 |

### A.2 应用、Workflow 与版本

| 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
| --- | --- | --- | --- |
| `/core/app/copy` | 复制 FastGPT 应用配置、基础信息、权限或工作流。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/create` | 创建 FastGPT 应用配置、基础信息、权限或工作流。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/del` | 删除 FastGPT 应用配置、基础信息、权限或工作流。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/detail` | 查询详情 FastGPT 应用配置、基础信息、权限或工作流。 | 可选，P0/P1 | 当前用于配置校验和探活评估 |
| `/core/app/folder/create` | 创建 FastGPT 应用文件夹或路径。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/folder/path` | 查询路径 FastGPT 应用文件夹或路径。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/getBasicInfo` | 查询基础信息 FastGPT 应用配置、基础信息、权限或工作流。 | 可选，P0/P1 | 当前用于配置校验和探活评估 |
| `/core/app/getPermission` | 查询权限 FastGPT 应用配置、基础信息、权限或工作流。 | 可选，P0/P1 | 当前用于配置校验和探活评估 |
| `/core/app/httpTools/create` | 创建 FastGPT HTTP 工具集。 | 可选，P1 | 当前仅交付验证，不进入业务主链路 |
| `/core/app/httpTools/getApiSchemaByUrl` | 按 URL 解析 API Schema FastGPT HTTP 工具集。 | 可选，P1 | 当前仅交付验证，不进入业务主链路 |
| `/core/app/httpTools/runTool` | 运行工具 FastGPT HTTP 工具集。 | 可选，P1 | 当前仅交付验证，不进入业务主链路 |
| `/core/app/httpTools/update` | 更新 FastGPT HTTP 工具集。 | 可选，P1 | 当前仅交付验证，不进入业务主链路 |
| `/core/app/list` | 查询列表 FastGPT 应用配置、基础信息、权限或工作流。 | 可选，P0/P1 | 当前用于配置校验和探活评估 |
| `/core/app/logs/exportLogs` | 处理 FastGPT 应用运行日志，用于排障、审计辅助和对账。 | 可选，P1 | 当前用于审计对账辅助评估 |
| `/core/app/logs/getLogKeys` | 处理 FastGPT 应用运行日志，用于排障、审计辅助和对账。 | 可选，P1 | 当前用于审计对账辅助评估 |
| `/core/app/logs/getUsers` | 处理 FastGPT 应用运行日志，用于排障、审计辅助和对账。 | 可选，P1 | 当前用于审计对账辅助评估 |
| `/core/app/logs/list` | 查询列表 FastGPT 应用运行日志，用于排障、审计辅助和对账。 | 可选，P1 | 当前用于审计对账辅助评估 |
| `/core/app/logs/updateLogKeys` | 处理 FastGPT 应用运行日志，用于排障、审计辅助和对账。 | 可选，P1 | 当前用于审计对账辅助评估 |
| `/core/app/mcpTools/create` | 创建 FastGPT MCP 工具集。 | 可选，P1 | 当前仅交付验证，不进入业务主链路 |
| `/core/app/mcpTools/getChildren` | 获取子工具 FastGPT MCP 工具集。 | 可选，P1 | 当前仅交付验证，不进入业务主链路 |
| `/core/app/mcpTools/getTools` | 获取工具列表 FastGPT MCP 工具集。 | 可选，P1 | 当前仅交付验证，不进入业务主链路 |
| `/core/app/mcpTools/runTool` | 运行工具 FastGPT MCP 工具集。 | 可选，P1 | 当前仅交付验证，不进入业务主链路 |
| `/core/app/mcpTools/update` | 更新 FastGPT MCP 工具集。 | 可选，P1 | 当前仅交付验证，不进入业务主链路 |
| `/core/app/resumeInheritPermission` | 恢复继承权限 FastGPT 应用配置、基础信息、权限或工作流。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/template/detail` | 查询详情 FastGPT 应用模板。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/template/list` | 查询列表 FastGPT 应用模板。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/tool/getPreviewNode` | 获取预览节点 FastGPT 工具节点、系统工具模板或路径。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/tool/getSystemToolTemplates` | 获取系统工具模板 FastGPT 工具节点、系统工具模板或路径。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/tool/path` | 查询路径 FastGPT 工具节点、系统工具模板或路径。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/transitionWorkflow` | 转换工作流 FastGPT 应用配置、基础信息、权限或工作流。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/update` | 更新 FastGPT 应用配置、基础信息、权限或工作流。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/app/version/detail` | 查询详情 FastGPT 应用版本，用于发布、回滚、灰度和版本映射。 | 是，P1 | 当前需要纳入版本映射设计 |
| `/core/app/version/latest` | 查询最新版本 FastGPT 应用版本，用于发布、回滚、灰度和版本映射。 | 是，P1 | 当前需要纳入版本映射设计 |
| `/core/app/version/list` | 查询列表 FastGPT 应用版本，用于发布、回滚、灰度和版本映射。 | 是，P1 | 当前需要纳入版本映射设计 |
| `/core/app/version/publish` | 发布 FastGPT 应用版本，用于发布、回滚、灰度和版本映射。 | 是，P1 | 当前需要纳入版本映射设计 |
| `/core/app/version/update` | 更新 FastGPT 应用版本，用于发布、回滚、灰度和版本映射。 | 是，P1 | 当前需要纳入版本映射设计 |
| `/core/workflow/debug` | 调试 FastGPT Workflow。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/workflow/getSandboxPackages` | 查询沙箱包 FastGPT Workflow。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |
| `/core/workflow/optimizeCode` | 优化代码 FastGPT Workflow。 | 可选，P2 | 当前不自动化管理 FastGPT 应用 |

### A.3 知识库、集合、分段与训练

| 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
| --- | --- | --- | --- |
| `/core/dataset/apiDataset/getCatalog` | 查询目录 FastGPT API 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/apiDataset/getPathNames` | 查询路径名称 FastGPT API 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/apiDataset/list` | 查询列表 FastGPT API 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/apiDataset/listExistId` | 查询已存在 ID FastGPT API 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create` | 创建 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create/apiCollection` | 创建 API 集合 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create/apiCollectionV2` | 创建 API 集合 V2 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create/backup` | 创建备份集合 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create/fileId` | 按文件 ID 创建 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create/images` | 按图片创建 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create/link` | 按链接创建 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create/localFile` | 按本地文件创建 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create/reTrainingCollection` | 重训集合 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create/template` | 按模板创建 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/create/text` | 按文本创建 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/delete` | 删除 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/detail` | 查询详情 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/export` | 导出 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/list` | 查询列表 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/listV2` | 处理 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/paths` | 查询路径 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/read` | 读取 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/scrollList` | 滚动查询列表 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/sync` | 同步 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/trainingDetail` | 查询训练详情 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/collection/update` | 更新 FastGPT 知识库集合。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/create` | 创建 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/createWithFiles` | 通过文件创建 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/delete` | 删除 FastGPT 知识库分段数据。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/detail` | 查询详情 FastGPT 知识库分段数据。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/getQuoteData` | 查询引用数据 FastGPT 知识库分段数据。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/index/create` | 创建 FastGPT 知识库分段索引。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/index/delete` | 删除 FastGPT 知识库分段索引。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/index/update` | 更新 FastGPT 知识库分段索引。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/insertData` | 插入数据 FastGPT 知识库分段数据。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/insertImages` | 插入图片数据 FastGPT 知识库分段数据。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/list` | 查询列表 FastGPT 知识库分段数据。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/pushData` | 推送数据 FastGPT 知识库分段数据。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/update` | 更新 FastGPT 知识库分段数据。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/data/v2/list` | 查询列表 FastGPT 知识库分段数据。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/delete` | 删除 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/detail` | 查询详情 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/exportAll` | 导出全部 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/file/getPreviewChunks` | 获取文件预览分块 FastGPT 知识库文件上传、预览或检索测试。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/file/getSearchTestImagePreviewUrls` | 获取检索测试图片预览 URL FastGPT 知识库文件上传、预览或检索测试。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/file/presignDatasetFilePostUrl` | 生成知识库文件上传预签名 URL FastGPT 知识库文件上传、预览或检索测试。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/file/presignSearchTestImage` | 生成检索测试图片预签名 URL FastGPT 知识库文件上传、预览或检索测试。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/folder/create` | 创建 FastGPT 知识库文件夹。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/getPermission` | 查询权限 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/list` | 查询列表 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/paths` | 查询路径 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/resumeInheritPermission` | 恢复继承权限 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/searchTest` | 检索测试 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/training/deleteTrainingData` | 删除训练数据 FastGPT 知识库训练任务。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/training/getDatasetTrainingQueue` | 查询训练队列 FastGPT 知识库训练任务。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/training/getTrainingDataDetail` | 查询训练数据详情 FastGPT 知识库训练任务。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/training/getTrainingError` | 查询训练错误 FastGPT 知识库训练任务。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/training/rebuildEmbedding` | 重建向量索引 FastGPT 知识库训练任务。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/training/updateTrainingData` | 更新训练数据 FastGPT 知识库训练任务。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/core/dataset/update` | 更新 FastGPT 知识库。 | 是，P1 | 当前需要用于知识库运行副本设计 |
| `/support/wallet/usage/createTrainingUsage` | 创建训练用量订单 FastGPT 知识库训练成本归集。 | 可选，P1 | 当前仅用于训练成本对账参考 |

### A.4 AI 模型、Skill 与沙箱

| 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
| --- | --- | --- | --- |
| `/core/ai/agent/createQuestionGuide` | 生成问题引导 FastGPT 应用问题引导。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/agent/v2/createQuestionGuide` | 生成问题引导 FastGPT 应用问题引导。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/model/delete` | 删除 FastGPT 模型配置。 | 可选，P1 | 当前用于环境能力展示/连通性验证 |
| `/core/ai/model/detail` | 查询详情 FastGPT 模型配置。 | 可选，P1 | 当前用于环境能力展示/连通性验证 |
| `/core/ai/model/getConfigJson` | 查询配置 JSON FastGPT 模型配置。 | 可选，P1 | 当前用于环境能力展示/连通性验证 |
| `/core/ai/model/getDefaultConfig` | 查询默认配置 FastGPT 模型配置。 | 可选，P1 | 当前用于环境能力展示/连通性验证 |
| `/core/ai/model/getMyModels` | 查询我的模型 FastGPT 模型配置。 | 可选，P1 | 当前用于环境能力展示/连通性验证 |
| `/core/ai/model/list` | 查询列表 FastGPT 模型配置。 | 可选，P1 | 当前用于环境能力展示/连通性验证 |
| `/core/ai/model/test` | 测试 FastGPT 模型配置。 | 可选，P1 | 当前用于环境能力展示/连通性验证 |
| `/core/ai/model/update` | 更新 FastGPT 模型配置。 | 可选，P1 | 当前用于环境能力展示/连通性验证 |
| `/core/ai/model/updateDefault` | 更新默认配置 FastGPT 模型配置。 | 可选，P1 | 当前用于环境能力展示/连通性验证 |
| `/core/ai/model/updateWithJson` | 用 JSON 更新 FastGPT 模型配置。 | 可选，P1 | 当前用于环境能力展示/连通性验证 |
| `/core/ai/optimizePrompt` | 优化 Prompt FastGPT AI 辅助能力。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/record/getRecord` | 查询 AI 记录 FastGPT AI 调用记录。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/sandbox/checkExist` | 检查是否存在 FastGPT 沙箱资源。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/sandbox/download` | 下载 FastGPT 沙箱资源。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/sandbox/fileOp` | 执行文件操作 FastGPT 沙箱资源。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/sandbox/getHtmlPreviewLink` | 获取 HTML 预览链接 FastGPT 沙箱资源。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/sandbox/list` | 查询列表 FastGPT 沙箱资源。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/sandbox/listRecursive` | 处理 FastGPT 沙箱资源。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/sandbox/read` | 读取 FastGPT 沙箱资源。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/sandbox/write` | 写入 FastGPT 沙箱资源。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/apps` | 查询 Skill 应用 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/copy` | 复制 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/create` | 创建 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/debugChat` | 处理 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/debugSession/chatItem/delete` | 删除 FastGPT Skill 调试会话。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/debugSession/delete` | 删除 FastGPT Skill 调试会话。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/debugSession/list` | 查询列表 FastGPT Skill 调试会话。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/debugSession/records` | 处理 FastGPT Skill 调试会话。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/debugSession/stop` | 停止 FastGPT Skill 调试会话。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/delete` | 删除 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/detail` | 查询详情 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/edit` | 编辑 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/export` | 导出 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/folder/create` | 创建 FastGPT Skill 文件夹或路径。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/folder/path` | 查询路径 FastGPT Skill 文件夹或路径。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/import` | 导入 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/list` | 查询列表 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/resumeInheritPermission` | 恢复继承权限 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/save-deploy` | 保存并部署 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/update` | 更新 FastGPT Skill 应用。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/version/list` | 查询列表 FastGPT Skill 版本。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/version/switch` | 切换 FastGPT Skill 版本。 | 否，P2/P3 | 当前不进入医疗主链路 |
| `/core/ai/skill/version/update` | 更新 FastGPT Skill 版本。 | 否，P2/P3 | 当前不进入医疗主链路 |

### A.5 插件、市场与模板

| 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
| --- | --- | --- | --- |
| `/core/plugin/admin/installWithUrl` | 通过 URL 安装 FastGPT 插件管理资源。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/pkg/confirm` | 确认 FastGPT 插件包。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/pkg/upload` | 上传 FastGPT 插件包。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/app/create` | 创建 FastGPT 插件工具关联应用。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/app/systemApps` | 查询系统应用 FastGPT 插件工具关联应用。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/app/update` | 更新 FastGPT 插件工具关联应用。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/delete` | 删除 FastGPT 插件工具。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/detail` | 查询详情 FastGPT 插件工具。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/list` | 查询列表 FastGPT 插件工具。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/runtimeConfig/detail` | 查询详情 FastGPT 插件工具运行配置。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/runtimeConfig/reset` | 重置 FastGPT 插件工具运行配置。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/runtimeConfig/update` | 更新 FastGPT 插件工具运行配置。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/tag/create` | 创建 FastGPT 插件工具标签。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/tag/delete` | 删除 FastGPT 插件工具标签。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/tag/update` | 更新 FastGPT 插件工具标签。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/tag/updateOrder` | 更新排序 FastGPT 插件工具标签。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/update` | 更新 FastGPT 插件工具。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/updateOrder` | 更新排序 FastGPT 插件工具。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/admin/tool/versions` | 查询版本 FastGPT 插件工具。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/team/toggleInstall` | 切换安装状态 团队 FastGPT 插件工具。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/team/tool/detail` | 查询详情 团队 FastGPT 插件工具。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/team/tool/list` | 查询列表 团队 FastGPT 插件工具。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/team/tool/versions` | 查询版本 团队 FastGPT 插件工具。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/core/plugin/toolTag/list` | 查询列表 FastGPT 插件工具标签。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/marketplace/[...path]` | 访问 FastGPT 市场资源代理。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |
| `/support/marketing/fetchWorkflow` | 处理 FastGPT 市场工作流模板。 | 否，P2/P3 | 当前不接，医疗插件须经 emoon 审查 |

### A.6 MCP、OpenAPI Key 与外链发布

| 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
| --- | --- | --- | --- |
| `/mcp/app/[key]/mcp` | 提供 FastGPT MCP 协议访问端点。 | 可选，P2 | 仅用于把 FastGPT 应用暴露给 emoon 或内部平台，不作为医院工具网关 |
| `/support/mcp/create` | 创建 FastGPT MCP Server 配置。 | 可选，P2 | 非医疗工具主链路；不能替代 emoon MCP Gateway |
| `/support/mcp/delete` | 删除 FastGPT MCP Server 配置。 | 可选，P2 | 非医疗工具主链路；按需用于清理 FastGPT 应用工具暴露 |
| `/support/mcp/list` | 查询列表 FastGPT MCP Server 配置。 | 可选，P2 | 非医疗工具主链路；按需用于配置巡检 |
| `/support/mcp/server/toolCall` | 调用工具 FastGPT MCP Server 工具。 | 可选，P2 | 仅用于 FastGPT 应用工具暴露验证，不进入医院系统调用路径 |
| `/support/mcp/server/toolList` | 查询工具列表 FastGPT MCP Server 工具。 | 可选，P2 | 仅用于 FastGPT 应用工具暴露验证，不进入医院系统调用路径 |
| `/support/mcp/update` | 更新 FastGPT MCP Server 配置。 | 可选，P2 | 非医疗工具主链路；如启用必须纳入 emoon 版本审计 |
| `/support/openapi/create` | 创建 FastGPT OpenAPI Key。 | 可选，P1 | 当前由运维/交付配置，不进运行链路 |
| `/support/openapi/delete` | 删除 FastGPT OpenAPI Key。 | 可选，P1 | 当前由运维/交付配置，不进运行链路 |
| `/support/openapi/health` | 健康检查 FastGPT OpenAPI Key。 | 可选，P1 | 当前可作为 OpenAPI Key 健康检查 |
| `/support/openapi/list` | 查询列表 FastGPT OpenAPI Key。 | 可选，P1 | 当前由运维/交付配置，不进运行链路 |
| `/support/openapi/update` | 更新 FastGPT OpenAPI Key。 | 可选，P1 | 当前由运维/交付配置，不进运行链路 |
| `/support/outLink/create` | 创建 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/delete` | 删除 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/dingtalk/[token]` | 处理 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/feishu/[token]` | 处理 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/list` | 查询列表 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/offiaccount/[token]` | 处理 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/playground/config` | 处理 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/playground/update` | 更新 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/update` | 更新 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/wechat/logout` | 处理 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/wechat/qrcode/generate` | 处理 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/wechat/qrcode/status` | 处理 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |
| `/support/outLink/wecom/[token]` | 处理 FastGPT 外链发布渠道。 | 否 | 当前不接，外部入口必须走 emoon |

### A.7 用户、团队与额度

| 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
| --- | --- | --- | --- |
| `/support/user/account/checkPswExpired` | 检查密码过期 FastGPT 用户账号。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/account/loginByPassword` | 密码登录 FastGPT 用户账号。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/account/loginout` | 退出登录 FastGPT 用户账号。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/account/preLogin` | 登录前检查 FastGPT 用户账号。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/account/resetExpiredPsw` | 重置过期密码 FastGPT 用户账号。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/account/tokenLogin` | Token 登录 FastGPT 用户账号。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/account/update` | 更新 FastGPT 用户账号。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/account/updatePasswordByOld` | 用旧密码改密 FastGPT 用户账号。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/team/limit/datasetSizeLimit` | 查询知识库容量限制 FastGPT 团队、套餐、额度或第三方能力。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/team/limit/exportDatasetLimit` | 查询知识库导出限制 FastGPT 团队、套餐、额度或第三方能力。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/team/limit/webSyncLimit` | 查询 Web 同步限制 FastGPT 团队、套餐、额度或第三方能力。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/team/plan/getTeamPlanStatus` | 查询团队套餐状态 FastGPT 团队、套餐、额度或第三方能力。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/team/thirtdParty/checkUsage` | 检查使用量 FastGPT 团队、套餐、额度或第三方能力。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/support/user/team/update` | 更新 FastGPT 团队、套餐、额度或第三方能力。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |

### A.8 文件、系统与通用资源

| 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
| --- | --- | --- | --- |
| `/common/file/presignAvatarPostUrl` | 生成头像上传预签名 URL FastGPT 通用文件资源。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/common/file/presignTempFilePostUrl` | 生成临时文件上传预签名 URL FastGPT 通用文件资源。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/common/file/read/[filename]` | 处理 FastGPT 通用文件资源。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/common/system/getInitData` | 处理 FastGPT 通用系统任务。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/common/system/unlockTask` | 解锁任务 FastGPT 通用系统任务。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/common/tracks/push` | 上报埋点 FastGPT 埋点数据。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/invoke/fileUpload` | 文件上传 FastGPT invoke 资源。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/invoke/userInfo` | 查询用户信息 FastGPT invoke 资源。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/system/file/[jwt]` | 处理 FastGPT 系统文件。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/system/file/download/[token]` | 处理 FastGPT 系统文件。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/system/file/upload/[token]` | 处理 FastGPT 系统文件。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/system/img/[...id]` | 读取 FastGPT 系统图片资源。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |
| `/system/plugin/[...path]` | 读取 FastGPT 插件静态资源。 | 否 | 当前不接，emoon 自有用户/团队/文件体系 |

### A.9 初始化、迁移与管理运维

| 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
| --- | --- | --- | --- |
| `/admin/clearInvalidData` | 清理无效数据 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |
| `/admin/initFeedbackFlags` | 初始化反馈标记 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |
| `/admin/initv4132` | 处理 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |
| `/admin/initv4140` | 处理 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |
| `/admin/initv4141` | 处理 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |
| `/admin/initv4143` | 处理 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |
| `/admin/initv4144` | 处理 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |
| `/admin/initv4145` | 处理 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |
| `/admin/initv41451` | 处理 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |
| `/admin/initv4147` | 处理 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |
| `/admin/support/appRegistration/create` | 创建 FastGPT 初始化、迁移或管理维护任务。 | 否 | 当前仅 FastGPT 运维升级使用 |

### A.10 代理、兼容与文档

| 接口 | 主要功能介绍 | emoon 是否需要对接 | 当前系统环境是否需要对接 |
| --- | --- | --- | --- |
| `/aiproxy/[...path]` | 处理 FastGPT AI Proxy 代理能力。 | 否 | 当前不进入医疗生产链路 |
| `/aiproxy/api/createChannel` | 创建代理渠道 FastGPT AI Proxy 代理能力。 | 否 | 当前不进入医疗生产链路 |
| `/devapidoc.json` | 导出 FastGPT 开发 API 文档描述。 | 否 | 当前不进入医疗生产链路 |
| `/lafApi/[...path]` | FastGPT 兼容或专业版代理转发接口。 | 否 | 当前不进入医疗生产链路 |
| `/openapi.json` | 导出 FastGPT OpenAPI 描述文件。 | 否 | 当前不进入医疗生产链路 |
| `/proApi/[...path]` | FastGPT 兼容或专业版代理转发接口。 | 否 | 当前不进入医疗生产链路 |