02 - REST API 接口

一、接口总览

Dodo-Agent 通过三个 Controller 暴露 HTTP 接口：

Controller路径前缀主要功能
AgentController/agent调用各智能体的流式接口
FileController/file文件上传、查询、删除
SessionController/session会话历史查询与删除

所有智能体接口均使用 SSE（Server-Sent Events） 协议流式输出 text/event-stream;charset=UTF-8。

二、AgentController

路径：/agent
文件：controller/AgentController.java
实现 InitializingBean，启动时通过 afterPropertiesSet() 初始化 Tavily MCP 工具回调。

2.1 联网智能问答

1
2
GET /agent/chat/stream
Content-Type: text/event-stream;charset=UTF-8
参数必填类型说明
query是String用户问题
conversationId是String会话 ID（用于加载历史）

底层 Agent：WebSearchReactAgent（builder 模式构建，maxRounds=5）

流式响应：参见 架构概览 - SSE 协议

2.2 文件智能问答

1
2
GET /agent/file/stream
Content-Type: text/event-stream;charset=UTF-8
参数必填类型说明
query是String用户问题
conversationId是String会话 ID
fileId是String已上传文件的 ID

底层 Agent：FileReactAgent

工作机制：

  • 工具 loadContent 会根据文件 embed 字段自动选择：
    • embed=1：使用 RAG 语义检索（适用大文件）
    • embed=0/null：直接加载完整文本内容（适用小文件）

2.3 PPT 智能生成

1
2
GET /agent/pptx/stream
Content-Type: text/event-stream;charset=UTF-8
参数必填类型说明
query是String用户需求（自然语言）
conversationId是String会话 ID

底层 Agent：PPTBuilderAgent（状态机驱动）

工作流（参见 07 PPT Builder 智能体）：

  1. PptIntentRecognizer 识别意图（CREATE/MODIFY/RESUME）
  2. RequirementStrategy → SearchStrategy → OutlineStrategy → SchemaStrategy → RenderStrategy → SuccessStrategy
  3. 任意状态中断后可通过 RESUME_PPT 意图恢复

2.4 深度研究

1
2
GET /agent/deep/stream
Content-Type: text/event-stream;charset=UTF-8
参数必填类型说明
query是String用户研究主题
conversationId是String会话 ID

底层 Agent：PlanExecuteAgent（Plan-Execute-Critique 循环）

4 阶段流程（参见 06 深度研究智能体）：

  1. 需求澄清（自动判断信息是否充足）
  2. 研究主题生成
  3. 计划-执行-批判循环（最多 3 轮，可并发执行）
  4. 综合报告生成

关键配置：

  • maxRounds=3：执行轮数上限
  • contextCharLimit=50000：上下文压缩阈值
  • maxToolRetries=2：工具重试次数
  • toolSemaphore：信号量控制并发（默认 3 个）

2.5 Skills 智能问答

1
2
GET /agent/skills/stream
Content-Type: text/event-stream;charset=UTF-8
参数必填类型说明
query是String用户问题
conversationId是String会话 ID
fileId否String可选文件 ID

底层 Agent：SkillsReactAgent

工具集（通过 ToolMergeUtils.mergeTools 合并）：

  • webSearchToolCallbacks（Tavily）
  • FileContentService（RAG 检索）
  • SkillsTool（技能加载）
  • FileSystemTools（read/write/edit/list/glob）
  • GrepTool（内容搜索）
  • BashTool（Shell 执行）

上下文压缩：默认使用 ContextPolicy.defaults()（token 阈值 60000，保留 4 轮工具）

2.6 停止 Agent 执行

1
GET /agent/stop?conversationId=xxx
参数必填类型说明
conversationId是String会话 ID

响应：

1
2
3
4
{
  "success": true,
  "message": "已停止执行"
}

底层逻辑：AgentTaskManager.stopTask() 通过 Redis Pub/Sub 跨实例广播停止信号（参见 11 会话与任务管理）。

三、FileController

路径：/file
文件：controller/FileController.java

3.1 上传文件

1
2
POST /file/upload
Content-Type: multipart/form-data
参数必填类型说明
file是MultipartFile文件（支持 PDF/DOC/DOCX/TXT/PNG/JPG/GIF/BMP）

返回：BaseResult<FileInfo>，包含 fileId / fileName / fileType / fileSize / status / embed 等字段

底层处理（参见 10 文件管理服务）：

  1. 生成 fileId（UUID）
  2. 上传到 MinIO
  3. 根据文件类型：
    • 文本文件 → FileParserService 解析（PDF/Word/TXT）
    • 图片文件 → Qwen-VL 多模态识别
  4. 大文件（≥5000 字符）触发向量化（PgVector）

3.2 获取文件信息

1
GET /file/info/{fileId}

3.3 获取文件内容

1
GET /file/content/{fileId}

返回 Map{ content: "...", length: 12345 }

3.4 删除文件

1
DELETE /file/{fileId}

同时删除 MinIO 文件和数据库记录

3.5 获取所有文件

1
GET /file/list

3.6 检查文件是否存在

1
GET /file/exists/{fileId}

四、SessionController

路径：/session
文件：controller/SessionController.java

4.1 查询会话详情

1
GET /session/{conversationId}

返回：SessionDetailVO，包含 conversationId / agentType / fileid / messages[]

messages[] 包含：question / answer / thinking / tools / reference / createTime / fileid / recommend

4.2 查询会话列表（分页）

1
GET /session/list?pageNum=1&pageSize=10

返回：PageResult<SessionListVO>，使用 AiSessionMapper.selectSessionListWithFirstRecord 关联查询首条消息

4.3 删除会话

1
DELETE /session/{conversationId}

事务操作：

  1. 删除 ai_file_info 表中关联数据
  2. 删除 ai_ppt_inst 表中关联数据
  3. 删除 ai_session 表中会话记录

五、通用响应格式

common/BaseResult.java 定义了所有 Controller 的统一返回结构：

1
2
3
4
5
6
{
  "code": 200,
  "success": true,
  "message": "ok",
  "data": { ... }
}
方法用途
BaseResult.newSuccess(data)成功
BaseResult.newError(message)失败
BaseResult.fail(code, message)自定义错误码

六、全局异常处理

exception/GlobalExceptionHandler.java 统一处理以下异常类型：

异常HTTP 状态说明
ConnectException503外部服务连接失败
ClosedChannelException503外部服务通道关闭
AsyncRequestNotUsableException-SSE 客户端断开（debug 日志）
IOException-SSE 写入失败（debug 日志）
HttpRequestMethodNotSupportedException405方法不允许
MissingPathVariableException400缺少路径变量
MethodArgumentTypeMismatchException400参数类型不匹配
IllegalArgumentException400参数异常
IllegalStateException500状态异常
BindException / MethodArgumentNotValidException400参数验证失败
ConstraintViolationException400参数约束违反
RuntimeException / Exception500通用异常

七、Swagger / OpenAPI

通过 springdoc-openapi 集成 Swagger UI，每个接口都标注了：

  • @Operation(summary=..., description=...)：接口说明
  • @Tag(name=...)：接口分类

启动后访问 http://localhost:9999/swagger-ui.html 即可查看。