KIAP 后端 API 文档总览

项目：KIAP 工业通用 AI 平台统一 API 前缀：/external/private/api 公网案例分享前缀：/external/public/api 鉴权头：DEFrame-UserId、DEFrame-TenantId、DEFrame-ExtendedInfo 文档版本基准：4f46278（2026-08-11）

统一响应体结构：

json

{
  "code": 0,
  "message": "success",
  "data": {},
  "ext": null
}

成功 code = 0；非零为业务错误码。所有业务异常由 @RestControllerAdvice 统一拦截，Controller 不自行处理异常；SSE 链路错误通过 error 事件推送，不抛异常。

模块索引

文档	业务域	覆盖 Controller	接口数
agent-module-api.md	我的 Agent	`AgentController`	14
agentcatalog-module-api.md	Agent 目录（类型/模板/分组/专家）	`AgentCatalogMetadata` / `AgentGroup` / `ExpertAgent`	7
model-module-api.md	我的模型	`ModelController`	14
conversation-module-api.md	我的对话	`Conversation` / `ConversationMessage` / `ConversationCase` / `PublicCase` / `ConversationTurn` / `Timeline`	19
conversation-extra-module-api.md	会话附加能力	`AgentDraftSuggestion` / `RecommendedWord`	2
data-module-api.md	我的数据	`DataController`	24
profile-module-api.md	用户档案	`ProfileController`	2
resource-artifact-module-api.md	资源与工件	`Artifact` / `ConversationAttachment` / `ResourcePolicy`	3
forecast-dataset-module-api.md	预测数据集	`ForecastDatasetController`	3

标注：本目录下标有"基于 Controller / DTO 代码声明生成"的接口为无法以真实请求实测、按代码声明编写，字段结构以源码为准。

通用约定

鉴权

所有 /external/private/api/** 接口需在请求头携带：

DEFrame-UserId：用户 ID
DEFrame-TenantId：租户 ID（多租户隔离，业务 Key 均含 tenantId）
DEFrame-ExtendedInfo：扩展信息 JSON（可空 {}）

分页

列表类接口响应 data 内含 records / total / size / current / pages。

文档标注说明

标注"真实请求"：已通过本地服务（http://localhost:8001）实测，示例为真实返回（中文值可能简化）。
标注"代码生成"：未实测执行，按代码声明写出，字段结构与类型以源码 DTO 为准。

模块速览

我的 Agent（`/external/private/api/agents`）

Agent 增删改查、复制、启停、运行（草稿进入会话）、详情、执行配置等。运行不提供独立 POST /agents/{id}/runs，仅由对话消息 SSE 创建 AgentRun。

Agent 目录（`/external/private/api/agent-types` 等）

平台级 Agent 类型枚举、可复用模板、分组管理、专家 Agent 列表。专家 Agent 必须在 expertMode 开启时显式指定，不自动切换。

我的模型（`/external/private/api/model`）

微调模型列表、详情、训练状态、微调详情、日志、数据集校验、创建/删除配对等。

我的对话（`/external/private/api/conversations`）

会话、消息、Turn/Block、时间线、案例（私有/公开分享）等核心对话能力。Agent 执行记录经 conversations/{id}/turns 的 activeRunId 暴露，无独立 REST。

会话附加（`/external/private/api`）

Agent 草稿建议（agent-draft-suggestion）、推荐词（recommended-words）。

我的数据（`/external/private/api/data`）

分类树、文件上传/预览/检索、KaiwuDB 数据源连接与 schema/table/tag/column/时序数据查询导出。注意：KaiwuDB 相关接口在未连接数据源时返回 500。

用户档案（`/external/private/api/profile`）

用户基础信息、统计数据、界面偏好（外观/显示模式/字体/行业）。

资源与工件（`/external/private/api`）

上传策略（resource-upload-policy）、对话附件上传（conversation-attachments/upload）、会话工件列表（conversations/{id}/artifacts）。usage 合法值：CONVERSATION_ATTACHMENT / AGENT_CONTEXT / CASE_ARTIFACT。

预测数据集（`/external/private/api`）

KaiwuDB 数据集目录、会话级预测数据集创建与详情。预测数据集创建会写入数据库并生成不可变 datasetVersion，本文档未实测执行。

KIAP 后端 API 文档总览 ​

模块索引 ​

通用约定 ​

鉴权 ​

分页 ​

文档标注说明 ​

模块速览 ​

我的 Agent（/external/private/api/agents） ​

Agent 目录（/external/private/api/agent-types 等） ​

我的模型（/external/private/api/model） ​

我的对话（/external/private/api/conversations） ​

会话附加（/external/private/api） ​

我的数据（/external/private/api/data） ​

用户档案（/external/private/api/profile） ​

资源与工件（/external/private/api） ​

预测数据集（/external/private/api） ​

相关设计文档 ​