agent-platform/docs/web-post-api-contract.md

Web 前端业务闭环与多服务 POST API 合约

本文档定义前端与后端服务之间的目标 API 合约。所有接口统一使用 POST，所有传输字段统一使用小驼峰，所有时间字段统一以 Time 结尾并使用 datetime 类型。多对多关系必须由中间表资源维护，前端可以一次性提交勾选结果，但服务端必须拆分落到绑定表。

1. 总体约定

1.1 请求与响应

项	约定
Base URL	/gateway
Method	全部使用 POST
Content-Type	application/json; charset=utf-8
Auth Header	Authorization: Bearer <accessToken>
User Header	x-user-id: <userId>
Request Header	x-request-id: <requestId>，可选
字段命名	前端和后端 API 传输层全部使用小驼峰
时间字段	字段名必须以 Time 结尾，类型必须是 datetime
关系字段	单对象关联使用 xxxId，多对多关系必须使用绑定资源
禁止传输层字段	不使用 enabled、版本字段、智能体类型、团队类型、给用户看的业务编号字段
数据库命名	数据库存储命名由服务内部处理，不能泄漏到 API DTO

统一响应包：

字段	类型	必填	说明
success	boolean	是	是否成功
data	object | array | null	是	成功数据
error	ApiError | null	是	错误信息
requestId	string	是	请求追踪 ID
serverTime	datetime	是	服务端响应时间

ApiError

字段	类型	必填	说明
errorType	string	是	机器可读错误类型
message	string	是	用户可读错误消息
details	object	否	字段错误或诊断信息

PageRequest

字段	类型	必填	默认	说明
page	integer	否	1	页码
pageSize	integer	否	20	每页数量，最大 200
keyword	string	否	空	搜索关键字
sortBy	string	否	createdTime	排序字段
sortOrder	"asc" | "desc"	否	"desc"	排序方向

PageResult<T>

字段	类型	必填	说明
items	T[]	是	当前页数据
total	integer	是	总数量
page	integer	是	当前页码
pageSize	integer	是	每页数量
hasMore	boolean	是	是否还有下一页

1.2 绑定关系原则

场景	错误做法	正确做法
新建智能体勾选技能	在 Agent 上保存技能 ID 数组	AgentSkillBinding 中间表
技能选择 MCP 工具	在 Skill 上保存工具 ID 数组	SkillToolBinding 中间表
团队选择智能体成员	在 Team 上保存成员数组	TeamMember 中间表
角色拥有权限	在 Role 上保存权限数组	RolePermissionBinding 中间表

前端交互可以是“一次提交”，例如创建智能体弹窗里勾选多个技能。API 应提供事务型接口，服务端负责创建主对象和绑定关系，保证绑定表落库。

2. 服务划分

服务	路由前缀	数据归属	对应界面	依赖关系
gatewayService	/gateway/system	聚合、健康检查、统一鉴权转发	Dashboard、全局错误	调用所有服务
identityService	/gateway/identity	用户、角色、权限绑定、API Key	Login、Settings	无
modelService	/gateway/model	模型配置、模型发现、模型测试	Models、Agent 创建右侧模型选择、Knowledge 设置	可调用外部模型供应商
toolService	/gateway/tool	MCP 服务、MCP 内部工具、凭据	Tools、Skill 工具选择	可连接外部 MCP
skillService	/gateway/skill	技能、技能工具绑定、技能安装、技能测试	Skills、Agent 创建技能勾选	依赖 toolService
agentService	/gateway/agent	智能体、智能体技能绑定、智能体运行	Agents、Sessions	依赖 modelService、skillService、memoryService
teamService	/gateway/team	团队、团队成员绑定、团队运行	Teams	依赖 agentService
sessionService	/gateway/session	会话、消息、运行请求	Sessions	依赖 agentService、workflowService
knowledgeService	/gateway/knowledge	知识库、文档、切片、检索设置、索引任务、评估	Knowledge	依赖 modelService
memoryService	/gateway/memory	记忆、向量检索、记忆归档	Memories、Agent 执行	依赖 modelService
workflowService	/gateway/workflow	应用、工作流、设计器、调试器	Workflow 设计器、未来多应用入口	依赖 agentService、teamService、toolService
runtimeService	/gateway/runtime	运行记录、节点运行、日志、Trace	Dashboard、调试器、运行详情	由执行侧写入

3. 页面交互与服务 API 闭环

页面	关键交互	调用服务	API 闭环
Login	登录、获取当前用户、退出	identityService	auth/login、auth/me、auth/logout
Dashboard	指标、服务健康、最近运行	gatewayService、runtimeService	dashboard/summary、health/services、runs/list
Models	模型列表、新建、编辑、删除、测试、发现模型	modelService	models/list、models/create、models/test、models/discover
Agents	列表、创建、编辑、技能勾选、运行测试	agentService、skillService、modelService	agents/createWithBindings、agentSkillBindings/sync、agentRuns/start
Sessions	会话创建、消息发送、触发运行、查看上下文	sessionService、agentService	messages/send 生成消息和运行请求
Tools	粘贴 MCP 配置、测试连接、发现内部工具、查看参数	toolService	mcpServers/importConfig、mcpServers/test、mcpTools/list
Skills	技能 CRUD、选择 MCP 工具、测试技能	skillService、toolService	skills/createWithBindings、skillToolBindings/sync、skills/test
Knowledge	知识库列表、进入内部、导入文档、检索测试、Rerank 设置	knowledgeService、modelService	bases/list、documents/create、settings/save、search/query
Memories	只读查看、筛选、语义搜索、详情	memoryService	memories/list、memories/search、memories/get
Teams	创建团队、添加成员、运行团队	teamService、agentService	teams/createWithMembers、teamMembers/sync、teamRuns/start
Settings	API Key 创建和撤销	identityService	apiKeys/create、apiKeys/revoke

4. 共享模型

4.1 Identity 模型

User

字段	类型	必填	说明
id	string	是	用户 ID
username	string	是	登录名
displayName	string | null	否	展示名
email	string | null	否	邮箱
metadata	object	是	扩展信息
lastLoginTime	datetime | null	否	最近登录时间
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

Role

字段	类型	必填	说明
id	string	是	角色 ID
name	string	是	角色名称
description	string | null	否	说明
permissionBindingCount	integer	是	权限绑定数量
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

RolePermissionBinding

字段	类型	必填	说明
id	string	是	绑定 ID
roleId	string	是	角色 ID
permission	string	是	权限标识
scopeType	string | null	否	范围类型
scopeId	string | null	否	范围对象 ID
createdTime	datetime	是	创建时间

ApiKey

字段	类型	必填	说明
id	string	是	API Key ID
name	string	是	名称
keyPrefix	string	是	密钥前缀
scopes	string | null	否	权限范围
expiresTime	datetime | null	否	过期时间
lastUsedTime	datetime | null	否	最近使用时间
revokedTime	datetime | null	否	撤销时间
createdTime	datetime	是	创建时间

4.2 Model 模型

Model

字段	类型	必填	说明
id	string	是	模型配置 ID
name	string	是	展示名称
providerType	string	是	供应商类型
providerBaseUrl	string	是	接入地址
hasProviderApiKey	boolean	是	是否已保存密钥
modelName	string	是	供应商模型名
capabilities	string[]	是	能力标签，例如 chat、embedding、rerank
contextWindow	integer | null	否	上下文窗口
maxOutputTokens	integer | null	否	最大输出 token
defaultTemperature	number | null	否	默认温度
timeoutSeconds	integer	是	超时时间
metadata	object	否	扩展信息
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

ModelTestResult

字段	类型	必填	说明
model	Model	是	被测试模型
content	string	是	文本输出
finishReason	string | null	否	结束原因
toolCalls	object[]	否	模型返回的工具调用
tokenUsage	object	是	token 用量
latencyMs	integer	是	调用耗时
testedTime	datetime	是	测试时间

4.3 Tool 模型

McpServer

字段	类型	必填	说明
id	string	是	MCP 服务 ID
name	string	是	服务名称
transport	"sse" | "streamableHttp" | "stdio"	是	连接协议
url	string | null	否	连接地址
headersMasked	object	是	脱敏请求头
timeoutSeconds	integer	是	连接超时
sseReadTimeoutSeconds	integer | null	否	SSE 读取超时
toolCount	integer	是	已发现工具数量
lastTestResult	ConnectionTestResult | null	否	最近连接测试
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

McpTool

字段	类型	必填	说明
id	string	是	MCP 内部工具 ID
mcpServerId	string	是	MCP 服务 ID
name	string	是	工具名称
description	string | null	否	工具说明
inputSchema	object	是	参数 schema
outputSchema	object	否	输出 schema
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

ConnectionTestResult

字段	类型	必填	说明
success	boolean	是	是否连通
message	string	是	结果说明
latencyMs	integer | null	否	延迟
toolCount	integer	是	可发现工具数
testedTime	datetime	是	测试时间

4.4 Skill 模型

Skill

字段	类型	必填	说明
id	string	是	技能 ID
name	string	是	技能名称
category	string	是	分类
description	string | null	否	技能说明
instruction	string	是	技能指令
parameterSchema	object	是	入参 schema
outputSchema	object	是	出参 schema
toolBindingCount	integer	是	已绑定 MCP 工具数量
metadata	object	否	扩展信息
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

SkillToolBinding

字段	类型	必填	说明
id	string	是	技能工具绑定 ID
skillId	string	是	技能 ID
toolId	string	是	MCP 工具 ID
orderIndex	integer	是	展示和调用顺序
parameterMapping	object	是	技能参数到工具参数的映射
config	object	是	局部配置
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

SkillInstallation

字段	类型	必填	说明
id	string	是	安装 ID
skillId	string	是	技能 ID
installScope	"global" | "user" | "agent" | "team"	是	安装范围
scopeId	string | null	否	范围对象 ID
config	object	是	安装配置
installedBy	string | null	否	安装人 ID
installedTime	datetime	是	安装时间
createdTime	datetime	是	创建时间

4.5 Agent 模型

Agent

字段	类型	必填	说明
id	string	是	智能体 ID
name	string	是	名称
ownerUserId	string | null	否	创建人 ID
modelId	string | null	否	绑定模型 ID
systemPrompt	string	是	系统提示词
skillBindingCount	integer	是	已绑定技能数量
memoryPolicy	AgentMemoryPolicy	是	记忆策略
runtimePolicy	AgentRuntimePolicy	是	运行策略
metadata	object	否	扩展信息
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

AgentSkillBinding

字段	类型	必填	说明
id	string	是	智能体技能绑定 ID
agentId	string	是	智能体 ID
skillId	string	是	技能 ID
orderIndex	integer	是	展示和调用顺序
config	object	是	局部配置
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

AgentMemoryPolicy

字段	类型	必填	说明
memoryScope	"session" | "user" | "agent" | "team" | "global"	是	记忆作用域
readMemory	boolean	是	是否读取记忆
writeMemory	boolean	是	是否写入记忆
maxItems	integer	是	最大召回数量
minScore	number	是	最低召回分数

AgentRuntimePolicy

字段	类型	必填	说明
temperature	number	是	温度
maxTokens	integer	是	最大输出 token
timeoutSeconds	integer	是	总超时
retryAttempts	integer	是	重试次数
retryBackoffMs	integer	是	重试退避毫秒
toolCallLimit	integer	是	单次运行最大工具调用次数
outputFormat	"text" | "json" | "markdown"	是	输出格式
humanApprovalPolicy	"never" | "beforeTool" | "beforeFinal"	是	人工审批策略

AgentRun

字段	类型	必填	说明
id	string	是	运行 ID
agentId	string	是	智能体 ID
sessionId	string | null	否	会话 ID
inputText	string | null	否	输入文本
input	object | null	否	结构化输入
outputText	string | null	否	输出文本
output	object | null	否	结构化输出
status	"queued" | "running" | "completed" | "failed" | "cancelled" | "paused"	是	运行状态
toolCallCount	integer	是	工具调用次数
errorMessage	string | null	否	错误消息
queuedTime	datetime | null	否	排队时间
startedTime	datetime | null	否	开始时间
finishedTime	datetime | null	否	结束时间
createdTime	datetime	是	创建时间

4.6 Session 模型

Session

字段	类型	必填	说明
id	string	是	会话 ID
appId	string	是	应用 ID
userId	string	是	用户 ID
channelType	string	是	渠道
title	string | null	否	标题
startedTime	datetime | null	否	开始时间
lastActiveTime	datetime | null	否	最近活跃时间
createdTime	datetime	是	创建时间

Message

字段	类型	必填	说明
id	string	是	消息 ID
sessionId	string	是	会话 ID
turnId	string | null	否	轮次 ID
role	"user" | "assistant" | "system" | "tool"	是	角色
contentType	"text" | "markdown" | "image" | "file" | "object"	是	内容类型
contentText	string | null	否	文本内容
content	object | null	否	结构化内容
createdTime	datetime	是	创建时间

RunRequest

字段	类型	必填	说明
id	string	是	请求 ID
sessionId	string	是	会话 ID
appId	string	是	应用 ID
workflowId	string | null	否	工作流 ID
agentId	string | null	否	智能体 ID
triggerType	string	是	触发方式
payload	object	是	负载
status	"queued" | "running" | "completed" | "failed" | "cancelled"	是	状态
createdTime	datetime	是	创建时间

4.7 Knowledge 模型

KnowledgeBase

字段	类型	必填	说明
id	string	是	知识库 ID
name	string	是	名称
description	string | null	否	说明
documentCount	integer	是	文档数
indexedDocumentCount	integer	是	已索引文档数
chunkCount	integer	是	切片数
settings	KnowledgeSettings	是	检索设置
metadata	object	否	扩展信息
archivedTime	datetime | null	否	归档时间
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

KnowledgeSettings

字段	类型	必填	说明
retrievalMode	"keyword" | "vector" | "hybrid"	是	检索模式
embeddingModelId	string | null	否	Embedding 模型 ID
rerankModelId	string | null	否	Rerank 模型 ID
chunkSize	integer	是	切片大小
chunkOverlap	integer	是	切片重叠
topK	integer	是	默认返回数量
minScore	number	是	最低分数
maxCandidates	integer	是	候选数量
keywordWeight	number	是	关键词权重
vectorWeight	number	是	向量权重
rerankWeight	number	是	Rerank 权重
queryRewrite	boolean	是	是否查询改写
requireCitations	boolean	是	是否要求引用

KnowledgeDocument

字段	类型	必填	说明
id	string	是	文档 ID
knowledgeBaseId	string	是	知识库 ID
title	string	是	标题
sourceType	"text" | "markdown" | "json" | "html" | "pdf" | "docx" | "url"	是	来源类型
sourceUri	string | null	否	来源地址
indexStatus	"draft" | "queued" | "indexed" | "failed" | "archived"	是	索引状态
contentHash	string | null	否	内容 hash
metadata	object	否	扩展信息
indexedTime	datetime | null	否	索引完成时间
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

KnowledgeChunk

字段	类型	必填	说明
id	string	是	切片 ID
knowledgeBaseId	string	是	知识库 ID
documentId	string	是	文档 ID
chunkIndex	integer	是	切片序号
contentText	string	是	切片内容
tokenCount	integer	是	token 数
embeddingModelId	string | null	否	向量模型 ID
metadata	object	否	扩展信息
createdTime	datetime	是	创建时间

4.8 Memory 模型

MemoryItem

字段	类型	必填	说明
id	string	是	记忆 ID
scopeType	"global" | "user" | "session" | "agent" | "team"	是	作用域类型
scopeId	string	是	作用域对象 ID
memoryType	string	是	记忆类型
contentText	string	是	记忆内容
content	object | null	否	结构化内容
metadata	object	是	扩展信息
embeddingModelId	string | null	否	Embedding 模型 ID
ownerAgentId	string | null	否	归属智能体 ID
userId	string | null	否	用户 ID
sessionId	string | null	否	会话 ID
sourceRef	string | null	否	来源引用
importanceScore	number	是	重要度
lastAccessedTime	datetime | null	否	最近访问时间
expiresTime	datetime | null	否	过期时间
archivedTime	datetime | null	否	归档时间
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

4.9 Team 模型

Team

字段	类型	必填	说明
id	string	是	团队 ID
name	string	是	名称
description	string | null	否	说明
ownerUserId	string | null	否	创建人 ID
coordinationMode	"supervisor" | "collaborative" | "sequential" | "debate"	是	协作模式
objective	string | null	否	目标
memberCount	integer	是	成员数量
policy	TeamPolicy	是	团队策略
metadata	object	否	扩展信息
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

TeamMember

字段	类型	必填	说明
id	string	是	成员绑定 ID
teamId	string	是	团队 ID
agentId	string	是	智能体 ID
role	string	是	团队内角色
responsibility	string | null	否	职责说明
orderIndex	integer	是	顺序
config	object	是	局部配置
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

TeamPolicy

字段	类型	必填	说明
maxRounds	integer	是	最大轮次
handoff	"supervisor" | "roundRobin" | "auto"	是	交接策略
failureMode	"stopOnCritical" | "continue" | "fallback"	是	失败策略
timeoutSeconds	integer	是	总超时
humanApprovalPolicy	"never" | "beforeFinal" | "onRisk"	是	人工审批策略

TeamRun

字段	类型	必填	说明
id	string	是	团队运行 ID
teamId	string	是	团队 ID
sessionId	string | null	否	会话 ID
inputText	string | null	否	输入文本
input	object | null	否	结构化输入
outputText	string | null	否	输出文本
output	object | null	否	结构化输出
status	"queued" | "running" | "completed" | "failed" | "cancelled" | "paused"	是	状态
createdTime	datetime	是	创建时间
startedTime	datetime | null	否	开始时间
finishedTime	datetime | null	否	结束时间

5. 按服务划分的 API

下方所有接口都是 POST。路径中的服务前缀代表网关转发目标。

5.1 gatewayService

接口	输入参数	输出	说明
POST /gateway/system/dashboard/summary	`timeRange:"24h"	"7d"	"30d"默认7d`
POST /gateway/system/health/get	无	service:string；status:string；`database:string	null；checkedTime:datetime`
POST /gateway/system/health/services	无	service:string；status:string；`downstreamServices:Array<{service:string,status:string,url:string,httpStatus:integer	null,errorMessage:string

5.2 identityService

接口	输入参数	输出	说明
POST /gateway/identity/auth/login	username:string 必填；password:string 必填	accessToken:string；tokenType:"bearer"；expiresTime:datetime；user:User	登录
POST /gateway/identity/auth/logout	无	ok:boolean	退出登录
POST /gateway/identity/auth/me	无	user:User；roles:Role[]；permissions:string[]	当前用户信息
POST /gateway/identity/users/list	PageRequest	PageResult<User>	用户列表
POST /gateway/identity/roles/list	PageRequest	PageResult<Role>	角色列表
POST /gateway/identity/rolePermissionBindings/list	PageRequest；roleId:string 必填	PageResult<RolePermissionBinding>	角色权限绑定列表
POST /gateway/identity/rolePermissionBindings/add	roleId:string 必填；permission:string 必填；`scopeType:string	null；scopeId:string	null`
POST /gateway/identity/rolePermissionBindings/remove	bindingId:string 必填	deleted:boolean；bindingId:string	删除角色权限绑定
POST /gateway/identity/permissions/check	userId:string 必填；permission:string 必填；`scopeType:string	null；scopeId:string	null`
POST /gateway/identity/apiKeys/list	PageRequest	PageResult<ApiKey>	API Key 列表
POST /gateway/identity/apiKeys/create	name:string 必填；`scopes:string	null；expiresTime:datetime	null`
POST /gateway/identity/apiKeys/revoke	apiKeyId:string 必填	ApiKey	撤销 API Key

5.3 modelService

接口	输入参数	输出	说明
POST /gateway/model/models/list	PageRequest；`providerType:string	null；capability:string	null`
POST /gateway/model/models/get	modelId:string 必填	Model	模型详情
POST /gateway/model/models/create	name:string 必填；providerType:string 必填；providerBaseUrl:string 必填；`providerApiKey:string	null；modelName:string必填；capabilities:string[]；contextWindow:integer	null；maxOutputTokens:integer
POST /gateway/model/models/update	modelId:string 必填；其余字段同 create，均可选	Model	更新模型
POST /gateway/model/models/delete	modelId:string 必填	deleted:boolean；modelId:string	删除模型
POST /gateway/model/models/test	modelId:string 必填；prompt:string 必填；`systemPrompt:string	null；temperature:number	null；maxTokens:integer
POST /gateway/model/models/discover	providerType:string 必填；providerBaseUrl:string 必填；`providerApiKey:string	null`	`models:Array<{modelName:string,displayName:string,capabilities:string[],contextWindow:integer

5.4 toolService

接口	输入参数	输出	说明
POST /gateway/tool/mcpServers/list	PageRequest	PageResult<McpServer>	MCP 服务列表
POST /gateway/tool/mcpServers/get	mcpServerId:string 必填	server:McpServer；tools:McpTool[]	MCP 服务详情
POST /gateway/tool/mcpServers/importConfig	config:object 必填；testConnection:boolean 默认 true；discoverTools:boolean 默认 true	servers:McpServer[]；testResults:ConnectionTestResult[]；discoveredTools:McpTool[]	支持粘贴 MCP 配置
POST /gateway/tool/mcpServers/create	name:string 必填；transport:string 默认 sse；`url:string	null；headers:object；timeoutSeconds:integer；sseReadTimeoutSeconds:integer	null`
POST /gateway/tool/mcpServers/update	mcpServerId:string 必填；其余字段同 create，均可选	McpServer	更新 MCP 服务
POST /gateway/tool/mcpServers/delete	mcpServerId:string 必填	deleted:boolean；mcpServerId:string	删除 MCP 服务
POST /gateway/tool/mcpServers/test	`mcpServerId:string	null；name:string	null；transport:string
POST /gateway/tool/mcpServers/discoverTools	mcpServerId:string 必填；refresh:boolean 默认 true	mcpServerId:string；tools:McpTool[]；discoveredTime:datetime	发现 MCP 内部工具
POST /gateway/tool/mcpTools/list	PageRequest；`mcpServerId:string	null`	PageResult<McpTool>
POST /gateway/tool/mcpTools/get	toolId:string 必填	McpTool	MCP 内部工具详情

5.5 skillService

接口	输入参数	输出	说明
POST /gateway/skill/skills/list	PageRequest；`category:string	null；toolId:string	null`
POST /gateway/skill/skills/get	skillId:string 必填	skill:Skill；toolBindings:SkillToolBinding[]	技能详情
POST /gateway/skill/skills/create	name:string 必填；category:string 必填；`description:string	null；instruction:string必填；parameterSchema:object；outputSchema:object；metadata:object`	Skill
POST /gateway/skill/skills/createWithBindings	skill:SkillCreateInput 必填；toolBindings:Array<{toolId:string,orderIndex:integer,parameterMapping:object,config:object}>	skill:Skill；toolBindings:SkillToolBinding[]	创建技能并写入工具绑定表
POST /gateway/skill/skills/update	skillId:string 必填；其余字段同 create，均可选	Skill	更新技能
POST /gateway/skill/skills/delete	skillId:string 必填	deleted:boolean；skillId:string	删除技能
POST /gateway/skill/skillToolBindings/list	PageRequest；skillId:string 必填	PageResult<SkillToolBinding>	技能工具绑定列表
POST /gateway/skill/skillToolBindings/add	skillId:string 必填；toolId:string 必填；`orderIndex:integer	null；parameterMapping:object；config:object`	SkillToolBinding
POST /gateway/skill/skillToolBindings/update	bindingId:string 必填；`orderIndex:integer	null；parameterMapping:object	null；config:object
POST /gateway/skill/skillToolBindings/remove	bindingId:string 必填	deleted:boolean；bindingId:string	删除技能工具绑定
POST /gateway/skill/skillToolBindings/sync	skillId:string 必填；toolBindings:Array<{toolId:string,orderIndex:integer,parameterMapping:object,config:object}>	skill:Skill；toolBindings:SkillToolBinding[]	用当前勾选结果同步中间表
POST /gateway/skill/skillInstallations/list	PageRequest；`skillId:string	null；installScope:string	null；scopeId:string
POST /gateway/skill/skillInstallations/install	skillId:string 必填；installScope:string 必填；`scopeId:string	null；config:object`	SkillInstallation
POST /gateway/skill/skillInstallations/uninstall	installationId:string 必填	deleted:boolean；installationId:string	卸载技能
POST /gateway/skill/skills/test	skillId:string 必填；input:object 必填；`agentId:string	null；sessionId:string	null`

SkillCreateInput

字段	类型	必填	说明
name	string	是	技能名称
category	string	是	分类
description	string | null	否	说明
instruction	string	是	技能指令
parameterSchema	object	是	入参 schema
outputSchema	object	是	出参 schema
metadata	object	否	扩展信息

5.6 agentService

接口	输入参数	输出	说明
POST /gateway/agent/agents/list	PageRequest；`ownerUserId:string	null；skillId:string	null；modelId:string
POST /gateway/agent/agents/get	agentId:string 必填	agent:Agent；skillBindings:AgentSkillBinding[]	智能体详情
POST /gateway/agent/agents/create	name:string 必填；`ownerUserId:string	null；modelId:string	null；systemPrompt:string；memoryPolicy:AgentMemoryPolicy；runtimePolicy:AgentRuntimePolicy；metadata:object`
POST /gateway/agent/agents/createWithBindings	agent:AgentCreateInput 必填；skillBindings:Array<{skillId:string,orderIndex:integer,config:object}>	agent:Agent；skillBindings:AgentSkillBinding[]	创建智能体并写入技能绑定表，适配新建弹窗勾选技能
POST /gateway/agent/agents/update	agentId:string 必填；其余字段同 create，均可选	Agent	更新智能体基础配置
POST /gateway/agent/agents/delete	agentId:string 必填；deleteRuns:boolean 默认 false	deleted:boolean；agentId:string	删除智能体
POST /gateway/agent/agentSkillBindings/list	PageRequest；agentId:string 必填	PageResult<AgentSkillBinding>	智能体技能绑定列表
POST /gateway/agent/agentSkillBindings/add	agentId:string 必填；skillId:string 必填；`orderIndex:integer	null；config:object`	AgentSkillBinding
POST /gateway/agent/agentSkillBindings/update	bindingId:string 必填；`orderIndex:integer	null；config:object	null`
POST /gateway/agent/agentSkillBindings/remove	bindingId:string 必填	deleted:boolean；bindingId:string	删除智能体技能绑定
POST /gateway/agent/agentSkillBindings/sync	agentId:string 必填；skillBindings:Array<{skillId:string,orderIndex:integer,config:object}>	agent:Agent；skillBindings:AgentSkillBinding[]	用当前勾选结果同步中间表
POST /gateway/agent/agentRuns/list	PageRequest；`agentId:string	null；sessionId:string	null；status:string
POST /gateway/agent/agentRuns/start	agentId:string 必填；`sessionId:string	null；inputText:string	null；input:object
POST /gateway/agent/agentRuns/get	runId:string 必填	AgentRun	运行详情
POST /gateway/agent/agentRuns/poll	runId:string 必填；`afterTime:datetime	null`	run:AgentRun；messages:Message[]；logs:object[]；`toolCalls:Array<{id:string,skillId:string
POST /gateway/agent/agentRuns/cancel	runId:string 必填；`reason:string	null`	AgentRun

AgentCreateInput

字段	类型	必填	说明
name	string	是	智能体名称
ownerUserId	string | null	否	创建人 ID
modelId	string | null	否	模型 ID
systemPrompt	string	是	系统提示词
memoryPolicy	AgentMemoryPolicy	是	记忆策略
runtimePolicy	AgentRuntimePolicy	是	运行策略
metadata	object	否	扩展信息

5.7 sessionService

接口	输入参数	输出	说明
POST /gateway/session/sessions/list	PageRequest；`appId:string	null；userId:string	null；channelType:string
POST /gateway/session/sessions/get	sessionId:string 必填	Session	会话详情
POST /gateway/session/sessions/create	appId:string 必填；userId:string 必填；channelType:string 默认 web；`title:string	null`	Session
POST /gateway/session/messages/list	PageRequest；sessionId:string 必填；`afterTime:datetime	null`	PageResult<Message>
POST /gateway/session/messages/send	sessionId:string 必填；contentText:string 必填；`contentType:"text"	"markdown"默认text；agentId:string	null；workflowId:string
POST /gateway/session/runRequests/list	PageRequest；sessionId:string 必填	PageResult<RunRequest>	会话运行请求
POST /gateway/session/context/get	sessionId:string 必填	session:Session；messageCount:integer；runCount:integer；recentRunRequests:RunRequest[]	会话上下文

5.8 knowledgeService

接口	输入参数	输出	说明
POST /gateway/knowledge/bases/list	PageRequest；includeArchived:boolean 默认 false	PageResult<KnowledgeBase>	知识库列表
POST /gateway/knowledge/bases/get	knowledgeBaseId:string 必填	KnowledgeBase	知识库详情
POST /gateway/knowledge/bases/create	name:string 必填；`description:string	null；settings:KnowledgeSettings	null；metadata:object`
POST /gateway/knowledge/bases/update	knowledgeBaseId:string 必填；`name:string	null；description:string	null；metadata:object
POST /gateway/knowledge/bases/archive	knowledgeBaseId:string 必填	KnowledgeBase	归档知识库
POST /gateway/knowledge/bases/restore	knowledgeBaseId:string 必填	KnowledgeBase	恢复知识库
POST /gateway/knowledge/settings/get	knowledgeBaseId:string 必填	KnowledgeSettings	获取检索设置
POST /gateway/knowledge/settings/save	knowledgeBaseId:string 必填；settings:KnowledgeSettings 必填	KnowledgeSettings	保存检索设置
POST /gateway/knowledge/documents/list	PageRequest；knowledgeBaseId:string 必填；`sourceType:string	null；indexStatus:string	null`
POST /gateway/knowledge/documents/parse	sourceType:string 必填；`sourceUri:string	null；contentText:string	null；contentBase64:string
POST /gateway/knowledge/documents/create	knowledgeBaseId:string 必填；title:string 必填；sourceType:string 必填；`sourceUri:string	null；contentText:string	null；contentBase64:string
POST /gateway/knowledge/documents/delete	documentId:string 必填	deleted:boolean；documentId:string	删除文档
POST /gateway/knowledge/documents/reindex	documentId:string 必填；`settings:KnowledgeSettings	null`	job:object
POST /gateway/knowledge/search/query	knowledgeBaseId:string 必填；query:string 必填；topK:integer 默认 5；filters:object；`rerankModelId:string	null；includeScoreDetail:boolean默认true`	`items:Array<{chunk:KnowledgeChunk,document:KnowledgeDocument,score:number,scoreDetail:object,citation:object
POST /gateway/knowledge/jobs/list	PageRequest；`knowledgeBaseId:string	null；documentId:string	null；status:string
POST /gateway/knowledge/jobs/create	knowledgeBaseId:string 必填；`documentId:string	null；jobType:string必填；payload:object`	job:object
POST /gateway/knowledge/jobs/retry	jobId:string 必填	job:object	重试任务
POST /gateway/knowledge/jobs/cancel	jobId:string 必填；`reason:string	null`	job:object
POST /gateway/knowledge/evals/list	PageRequest；knowledgeBaseId:string 必填	PageResult<object>	评估集
POST /gateway/knowledge/evals/create	knowledgeBaseId:string 必填；query:string 必填；expected:string 必填	item:object	新增评估问题
POST /gateway/knowledge/evals/run	knowledgeBaseId:string 必填；`evalIds:string[]	null`	job:object

5.9 memoryService

接口	输入参数	输出	说明
POST /gateway/memory/memories/list	PageRequest；`scopeType:string	null；scopeId:string	null；memoryType:string
POST /gateway/memory/memories/get	memoryId:string 必填	MemoryItem	记忆详情
POST /gateway/memory/memories/search	query:string 必填；`scopeType:string	null；scopeId:string	null；ownerAgentId:string
POST /gateway/memory/memories/create	scopeType:string 必填；scopeId:string 必填；memoryType:string 必填；contentText:string 必填；`content:object	null；metadata:object；ownerAgentId:string	null；userId:string
POST /gateway/memory/memories/archive	memoryId:string 必填	MemoryItem	归档记忆
POST /gateway/memory/memories/delete	memoryId:string 必填	deleted:boolean；memoryId:string	删除记忆

5.10 teamService

接口	输入参数	输出	说明
POST /gateway/team/teams/list	PageRequest；`ownerUserId:string	null；agentId:string	null`
POST /gateway/team/teams/get	teamId:string 必填	team:Team；members:TeamMember[]	团队详情
POST /gateway/team/teams/create	name:string 必填；`description:string	null；ownerUserId:string	null；coordinationMode:string；objective:string
POST /gateway/team/teams/createWithMembers	team:TeamCreateInput 必填；`members:Array<{agentId:string,role:string,responsibility:string	null,orderIndex:integer,config:object}>`	team:Team；members:TeamMember[]
POST /gateway/team/teams/update	teamId:string 必填；其余字段同 create，均可选	Team	更新团队
POST /gateway/team/teams/delete	teamId:string 必填；deleteRuns:boolean 默认 false	deleted:boolean；teamId:string	删除团队
POST /gateway/team/teamMembers/list	PageRequest；teamId:string 必填	PageResult<TeamMember>	团队成员列表
POST /gateway/team/teamMembers/add	teamId:string 必填；agentId:string 必填；role:string 必填；`responsibility:string	null；orderIndex:integer	null；config:object`
POST /gateway/team/teamMembers/update	memberId:string 必填；`role:string	null；responsibility:string	null；orderIndex:integer
POST /gateway/team/teamMembers/remove	memberId:string 必填	deleted:boolean；memberId:string	删除团队成员
POST /gateway/team/teamMembers/sync	teamId:string 必填；`members:Array<{agentId:string,role:string,responsibility:string	null,orderIndex:integer,config:object}>`	team:Team；members:TeamMember[]
POST /gateway/team/teamRuns/list	PageRequest；`teamId:string	null；sessionId:string	null；status:string
POST /gateway/team/teamRuns/start	teamId:string 必填；`sessionId:string	null；inputText:string	null；input:object
POST /gateway/team/teamRuns/get	runId:string 必填	TeamRun	团队运行详情
POST /gateway/team/teamRuns/cancel	runId:string 必填；`reason:string	null`	TeamRun

TeamCreateInput

字段	类型	必填	说明
name	string	是	团队名称
description	string | null	否	说明
ownerUserId	string | null	否	创建人 ID
coordinationMode	string	是	协作模式
objective	string | null	否	目标
policy	TeamPolicy	是	团队策略
metadata	object	否	扩展信息

5.11 workflowService

Workflow

字段	类型	必填	说明
id	string	是	工作流 ID
appId	string	是	应用 ID
name	string	是	名称
workflowType	string	是	工作流类型
dsl	WorkflowDsl	是	设计器 DSL
createdTime	datetime	是	创建时间
updatedTime	datetime	是	更新时间

WorkflowDsl

字段	类型	必填	说明
name	string	是	工作流名称
nodes	WorkflowNode[]	是	节点列表
edges	WorkflowEdge[]	是	连线列表

接口	输入参数	输出	说明
POST /gateway/workflow/apps/list	PageRequest	PageResult<App>	应用列表
POST /gateway/workflow/apps/create	name:string 必填；`description:string	null；ownerUserId:string	null；settings:object`
POST /gateway/workflow/apps/update	appId:string 必填；`name:string	null；description:string	null；settings:object
POST /gateway/workflow/apps/delete	appId:string 必填	deleted:boolean；appId:string	删除应用
POST /gateway/workflow/workflows/list	PageRequest；`appId:string	null；workflowType:string	null`
POST /gateway/workflow/workflows/get	workflowId:string 必填	Workflow	工作流详情
POST /gateway/workflow/workflows/create	appId:string 必填；name:string 必填；workflowType:string 必填；dsl:WorkflowDsl	Workflow	创建工作流
POST /gateway/workflow/workflows/save	workflowId:string 必填；`name:string	null；dsl:WorkflowDsl` 必填	Workflow
POST /gateway/workflow/workflows/delete	workflowId:string 必填	deleted:boolean；workflowId:string	删除工作流
POST /gateway/workflow/workflows/validate	dsl:WorkflowDsl 必填	valid:boolean；`diagnostics:Array<{severity:string,diagnosticId:string,message:string,nodeId:string	null,edgeIndex:integer
POST /gateway/workflow/debug/start	`workflowId:string	null；dsl:WorkflowDsl	null；input:object；breakpoints:string[]`
POST /gateway/workflow/debug/step	debugSessionId:string 必填；`action:"next"	"continue"	"pause"必填；inputPatch:object
POST /gateway/workflow/debug/stop	debugSessionId:string 必填	stopped:boolean；finishedTime:datetime	停止调试

5.12 runtimeService

WorkflowRun

字段	类型	必填	说明
id	string	是	运行 ID
appId	string	是	应用 ID
workflowId	string	是	工作流 ID
sessionId	string | null	否	会话 ID
parentRunId	string | null	否	父运行 ID
rootRunId	string | null	否	根运行 ID
runType	string	是	运行类型
status	"pending" | "running" | "completed" | "failed" | "cancelled" | "paused"	是	状态
triggerType	string	是	触发类型
priority	integer	是	优先级
currentNodeCount	integer	是	当前节点数
startedTime	datetime | null	否	开始时间
finishedTime	datetime | null	否	结束时间
createdTime	datetime	是	创建时间

NodeRun

字段	类型	必填	说明
id	string	是	节点运行 ID
runId	string	是	运行 ID
nodeId	string	是	节点 ID
nodeType	string	是	节点类型
attemptNo	integer	是	第几次尝试
status	"pending" | "queued" | "running" | "completed" | "failed" | "skipped"	是	状态
outputText	string | null	否	输出文本
output	object | null	否	结构化输出
scheduledTime	datetime | null	否	计划时间
timeoutTime	datetime | null	否	超时时间
queuedTime	datetime | null	否	排队时间
createdTime	datetime	是	创建时间

接口	输入参数	输出	说明
POST /gateway/runtime/runs/list	PageRequest；`appId:string	null；workflowId:string	null；sessionId:string
POST /gateway/runtime/runs/get	runId:string 必填	WorkflowRun	运行详情
POST /gateway/runtime/nodeRuns/list	PageRequest；runId:string 必填；`status:string	null`	PageResult<NodeRun>
POST /gateway/runtime/executionLogs/list	PageRequest；runId:string 必填；`nodeRunId:string	null；level:string	null`
POST /gateway/runtime/traceSpans/list	PageRequest；runId:string 必填；`nodeRunId:string	null`	PageResult<object>

6. 新建智能体勾选技能的标准流程

这个流程解决“界面勾选技能”和“数据库必须中间表”的冲突。

1. 打开弹窗时，前端调用 POST /gateway/model/models/list 获取可选模型。
2. 打开弹窗时，前端调用 POST /gateway/skill/skills/list 获取可选技能。
3. 用户填写智能体名称、提示词、记忆策略、运行策略，并勾选技能。
4. 前端提交 POST /gateway/agent/agents/createWithBindings。
5. agentService 在一个事务内创建 Agent，再批量创建 AgentSkillBinding。
6. 返回 agent 和 skillBindings，前端直接刷新列表和详情。

请求体：

字段	类型	必填	说明
agent	AgentCreateInput	是	智能体基础信息
skillBindings	Array<{skillId:string,orderIndex:integer,config:object}>	是	勾选技能对应的绑定行

响应体：

字段	类型	必填	说明
agent	Agent	是	创建后的智能体
skillBindings	AgentSkillBinding[]	是	创建后的绑定行

编辑智能体时，如果用户重新勾选技能，前端调用 POST /gateway/agent/agentSkillBindings/sync。该接口以当前勾选结果为准，由 agentService 自动新增、更新、删除绑定行。

7. 前端迁移清单

优先级	任务	说明
P0	API Client 改造	移除 get、patch、delete 调用，统一 post
P0	DTO 改造	所有请求和响应字段改为小驼峰
P0	时间字段改造	所有时间字段改为 createdTime、updatedTime、startedTime 这类命名
P0	Agent 创建闭环	创建弹窗改调 agents/createWithBindings
P0	Agent 编辑闭环	技能勾选变更改调 agentSkillBindings/sync
P0	Skill 工具绑定	技能页改用 skillToolBindings/sync
P0	Team 成员绑定	团队页改用 teamMembers/sync
P1	MCP 闭环	工具页支持 importConfig、test、discoverTools
P1	Knowledge 落库	Jobs、Evaluation、Settings 全部接 knowledgeService
P1	Skills 去 mock	Skills 页接 skillService
P2	Workflow 设计器	挂路由并接入 workflowService