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

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

本文档用于前端、网关、后端服务共同对齐。它不是当前接口的逐字转录，而是面向产品落地的目标合约：所有请求统一使用 POST，页面只使用 id 做关联，不向用户暴露 code、版本、启用禁用、原始 JSON 等内部概念。

1. 统一规则

1.1 请求规则

项	约定
Base URL	/gateway
Method	全部使用 POST
Content-Type	application/json; charset=utf-8
Auth	Authorization: Bearer <access_token>
User Context	x-user-id: <user_id>
Request ID	前端可传 x-request-id，后端必须回传 request_id
Timezone	入库与接口输出建议 UTC，前端展示固定为 YYYY-MM-DD HH:mm

1.2 字段规则

规则	说明
*_time	所有以 time 结尾的字段类型都必须是 datetime，JSON 传输为 ISO 8601 字符串，后端必须映射为数据库 datetime 类型
关联字段	单对象关联使用 id，例如 agent_id、model_id；多对多关系必须使用中间表资源，不允许在主对象上直接保存 xxx_ids
批量参数	一次性命令可以使用 ids 数组，例如批量运行评估；但这类数组不能代表持久化关系
禁止前端字段	前端页面、接口入参、业务文案不使用 code、version_no、enabled
状态字段	不使用启用禁用状态。仅运行、任务、文档索引、API Key 撤销等真实生命周期允许有状态
JSON 字段命名	对外统一使用 metadata、config、policy、schema，后端可内部映射到 *_json
Agent	不暴露智能体类型，不暴露版本概念，不直接选择工具，只选择模型、技能、记忆、运行策略
Tool	前端以 MCP 服务为管理对象，一个 MCP 服务下可发现多个工具；不提供“新增单个 Tool”的主流程
Knowledge	先管理知识库列表，再进入单个知识库内部管理文档、检索、评估、任务、设置

1.3 通用响应包

所有接口都返回统一包裹格式。

字段	类型	必填	说明
success	boolean	是	请求是否成功
data	object | array | null	是	成功时为业务数据，失败时为 null
error	ApiError | null	是	失败时为错误对象，成功时为 null
request_id	string	是	请求追踪 ID
server_time	datetime	是	服务端响应时间

ApiError

字段	类型	必填	说明
error_code	string	是	机器可读错误码
message	string	是	用户可读错误消息
details	object	否	字段级错误或调试信息，不直接展示原始堆栈

1.4 分页、排序、筛选

PageRequest

字段	类型	必填	默认	说明
page	integer	否	1	页码，从 1 开始
page_size	integer	否	20	每页数量，最大 200
keyword	string	否	空	搜索关键字
sort_by	string	否	created_time	排序字段，必须是后端白名单字段
sort_order	"asc" | "desc"	否	"desc"	排序方向

PageResult<T>

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

2. 前端界面与业务闭环排查

模块	路由	当前界面能力	主要问题	API 闭环要求
登录	/login	账号密码登录、写入 token	缺少 me/logout 闭环	增加当前用户、退出登录、权限检查
仪表盘	/dashboard	展示智能体、会话、运行、服务健康	多个接口聚合，刷新成本高	提供 dashboard/summary，详情仍可按模块查
模型	/models	模型列表、新建、编辑、删除、测试	目前仍有 provider 细节，字段偏技术	模型管理只围绕“模型配置列表”，Agent 只用 model_id
智能体	/agents	列表、创建、编辑、技能选择、测试弹窗	执行是本地模拟，仍有版本、类型、状态残留	去版本化，提供配置保存、运行、轮询、取消、运行详情
会话	/sessions	会话列表、创建、消息发送、上下文弹窗	发送消息后未形成真实 Agent/Workflow 执行闭环	消息发送要可触发运行请求并返回最新消息
记忆	/memories	记忆列表、筛选、详情弹窗	不应有人工新建主入口；仍有结构化字段展示痕迹	提供只读、搜索、详情、归档；创建主要给系统内部调用
工具	/tools	MCP 服务列表、连接弹窗、详情抽屉	缺少粘贴 MCP 配置、连接测试、工具发现；不应添加单个 Tool	以 MCP 服务为单位导入、测试、发现、展示内部工具参数
技能	/skills	当前是本地 mock CRUD	未接真实 API，仍有状态字段	提供技能定义、参数 schema、工具引用、安装、测试执行
知识库	/knowledge	知识库列表、文档、搜索、设置、任务、评估	部分是 mock；任务、评估、设置未落库	以知识库为入口，提供文档解析、索引、检索、Rerank 设置、评估
团队	/teams	团队列表、创建、成员、运行	仍有类型、状态、版本残留	去版本化，团队直接保存协作配置并可启动运行
设置	/settings	API Key 列表、新建、撤销	状态展示可保留为安全生命周期，不是启用禁用	API Key 创建后只展示一次密钥，支持撤销
Workflow 设计器	未挂路由	前端类型存在，但无页面	业务闭环缺失	预留设计、校验、调试、运行查询 API
模型供应商	页面存在未挂路由	可创建/发现 provider	与当前产品“模型列表管理”冲突	不作为主入口，能力可并入模型创建弹窗或后端内部

3. 共享数据模型

3.1 Auth

User

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

Role

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

RolePermissionBinding

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

3.2 Model

Model

字段	类型	必填	说明
id	string	是	模型配置 ID
name	string	是	前端展示名称
provider_type	string	是	供应商类型，例如 openai、ollama、custom
provider_base_url	string	是	接入地址
has_provider_api_key	boolean	是	是否已保存密钥
model_name	string	是	供应商模型名
capabilities	string[]	是	能力，例如 chat、embedding、rerank
context_window	integer | null	否	上下文窗口
max_output_tokens	integer | null	否	最大输出 token
default_temperature	number | null	否	默认温度
timeout_seconds	integer	是	调用超时时间
metadata	object	否	扩展信息
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

ModelTestResult

字段	类型	必填	说明
model	Model	是	被测试模型
content	string	是	文本输出
finish_reason	string | null	否	结束原因
tool_calls	object[]	否	模型返回的工具调用
usage	object	是	token 用量
latency_ms	integer	是	调用耗时

3.3 Agent

Agent

字段	类型	必填	说明
id	string	是	智能体 ID
name	string	是	名称
owner_user_id	string | null	否	创建人 ID
model_id	string | null	否	绑定模型 ID
system_prompt	string	是	系统提示词，仅编辑页使用
skill_binding_count	integer	是	已绑定技能数量
memory_policy	AgentMemoryPolicy	是	记忆配置
runtime_policy	AgentRuntimePolicy	是	运行策略
metadata	object	否	扩展信息
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

AgentSkillBinding

Agent 与 Skill 是多对多关系，必须通过该中间表维护。Agent 主表和 Agent DTO 不保存技能 ID 数组。

字段	类型	必填	说明
id	string	是	智能体技能绑定 ID
agent_id	string	是	智能体 ID
skill_id	string	是	技能 ID
order_index	integer	是	技能展示和调用优先级顺序
config	object	是	该智能体使用该技能时的局部配置
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

AgentMemoryPolicy

字段	类型	必填	说明
memory_scope	"session" | "user" | "agent" | "team" | "global"	是	记忆作用域
read_memory	boolean	是	是否读取记忆
write_memory	boolean	是	是否写入记忆
max_items	integer	是	最大召回数量
min_score	number	是	最低召回分数

AgentRuntimePolicy

字段	类型	必填	说明
temperature	number	是	温度
max_tokens	integer	是	最大输出 token
timeout_seconds	integer	是	总超时时间
retry_attempts	integer	是	最大重试次数
retry_backoff_ms	integer	是	重试退避毫秒
tool_call_limit	integer	是	单次运行最大工具调用次数
output_format	"text" | "json" | "markdown"	是	输出格式
human_approval_policy	"never" | "before_tool" | "before_final"	是	人工审批策略

AgentRun

字段	类型	必填	说明
id	string	是	运行 ID
agent_id	string	是	智能体 ID
session_id	string | null	否	会话 ID
input_text	string | null	否	输入文本
input	object | null	否	结构化输入
output_text	string | null	否	输出文本
output	object | null	否	结构化输出
status	"queued" | "running" | "completed" | "failed" | "cancelled" | "paused"	是	运行生命周期
tool_call_count	integer	是	工具调用次数
error_message	string | null	否	错误消息
queued_time	datetime | null	否	排队时间
started_time	datetime | null	否	开始时间
finished_time	datetime | null	否	结束时间
created_time	datetime	是	创建时间

3.4 Session

Session

字段	类型	必填	说明
id	string	是	会话 ID
app_id	string	是	应用 ID
user_id	string	是	用户 ID
channel_type	string	是	渠道，例如 web
title	string | null	否	会话标题
started_time	datetime | null	否	开始时间
last_active_time	datetime | null	否	最近活跃时间
created_time	datetime	是	创建时间

Message

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

RunRequest

字段	类型	必填	说明
id	string	是	请求 ID
session_id	string	是	会话 ID
app_id	string	是	应用 ID
workflow_id	string | null	否	工作流 ID
agent_id	string | null	否	智能体 ID
trigger_type	string	是	触发类型
payload	object	是	请求负载
status	"queued" | "running" | "completed" | "failed" | "cancelled"	是	请求状态
created_time	datetime	是	创建时间

3.5 Tool and MCP

McpServer

字段	类型	必填	说明
id	string	是	MCP 服务 ID
name	string	是	服务名称
transport	"sse" | "streamable_http" | "stdio"	是	连接协议
url	string | null	否	SSE 或 HTTP 地址
headers_masked	object	是	脱敏请求头
timeout_seconds	integer	是	连接超时
sse_read_timeout_seconds	integer | null	否	SSE 读取超时
tool_count	integer	是	已发现工具数量
last_test_result	ConnectionTestResult | null	否	最近连接测试
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

McpTool

字段	类型	必填	说明
id	string	是	MCP 内部工具 ID
mcp_server_id	string	是	MCP 服务 ID
name	string	是	工具名称
description	string | null	否	工具说明
input_schema	object	是	参数 schema
output_schema	object	否	输出 schema
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

ConnectionTestResult

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

3.6 Skill

Skill

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

SkillToolBinding

Skill 与 MCP Tool 是多对多关系，必须通过该中间表维护。Skill 主表和 Skill DTO 不保存工具 ID 数组。

字段	类型	必填	说明
id	string	是	技能工具绑定 ID
skill_id	string	是	技能 ID
tool_id	string	是	MCP 工具 ID
order_index	integer	是	工具展示和调用优先级顺序
parameter_mapping	object	是	技能参数到工具参数的映射
config	object	是	该技能使用该工具时的局部配置
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

SkillInstallation

字段	类型	必填	说明
id	string	是	安装 ID
skill_id	string	是	技能 ID
install_scope	"global" | "user" | "agent" | "team"	是	安装范围
scope_id	string | null	否	范围对象 ID
config	object	是	安装配置
installed_by	string | null	否	安装人 ID
installed_time	datetime	是	安装时间
created_time	datetime	是	创建时间

3.7 Knowledge

KnowledgeBase

字段	类型	必填	说明
id	string	是	知识库 ID
name	string	是	知识库名称
description	string | null	否	说明
document_count	integer	是	文档数量
indexed_document_count	integer	是	已索引文档数量
chunk_count	integer	是	切片数量
settings	KnowledgeSettings	是	检索设置
metadata	object	否	扩展信息
archived_time	datetime | null	否	归档时间
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

KnowledgeSettings

字段	类型	必填	说明
retrieval_mode	"keyword" | "vector" | "hybrid"	是	检索模式
embedding_model_id	string | null	否	Embedding 模型 ID
rerank_model_id	string | null	否	Rerank 模型 ID
chunk_size	integer	是	切片大小
chunk_overlap	integer	是	切片重叠
top_k	integer	是	默认返回数量
min_score	number	是	最低分数
max_candidates	integer	是	候选数量
keyword_weight	number	是	关键词权重
vector_weight	number	是	向量权重
rerank_weight	number	是	Rerank 权重
query_rewrite	boolean	是	是否查询改写
require_citations	boolean	是	是否要求引用来源

KnowledgeDocument

字段	类型	必填	说明
id	string	是	文档 ID
knowledge_base_id	string	是	知识库 ID
title	string	是	标题
source_type	"text" | "markdown" | "json" | "html" | "pdf" | "docx" | "url"	是	来源类型
source_uri	string | null	否	来源地址
index_status	"draft" | "queued" | "indexed" | "failed" | "archived"	是	索引状态
content_hash	string | null	否	内容 hash
metadata	object	否	扩展信息
indexed_time	datetime | null	否	索引完成时间
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

KnowledgeChunk

字段	类型	必填	说明
id	string	是	切片 ID
knowledge_base_id	string	是	知识库 ID
document_id	string	是	文档 ID
chunk_index	integer	是	切片序号
content_text	string	是	切片内容
token_count	integer	是	token 数
embedding_model_id	string | null	否	向量模型 ID
metadata	object	否	扩展信息
created_time	datetime	是	创建时间

KnowledgeSearchResult

字段	类型	必填	说明
chunk	KnowledgeChunk	是	命中的切片
document	KnowledgeDocument	是	来源文档
score	number	是	最终分数
score_detail	object	是	分数组成
citation	object	否	引用信息

KnowledgeJob

字段	类型	必填	说明
id	string	是	任务 ID
knowledge_base_id	string	是	知识库 ID
document_id	string | null	否	文档 ID
job_type	"parse" | "index" | "reindex" | "sync" | "delete"	是	任务类型
status	"queued" | "running" | "completed" | "failed" | "cancelled"	是	任务状态
progress	integer	是	进度 0 到 100
message	string | null	否	任务消息
error_message	string | null	否	错误消息
created_time	datetime	是	创建时间
started_time	datetime | null	否	开始时间
finished_time	datetime | null	否	完成时间

3.8 Memory

MemoryItem

字段	类型	必填	说明
id	string	是	记忆 ID
scope_type	"global" | "user" | "session" | "agent" | "team"	是	作用域类型
scope_id	string	是	作用域对象 ID
memory_type	string	是	记忆类型
content_text	string	是	记忆内容
content	object | null	否	结构化内容
metadata	object	是	扩展信息
embedding_model_id	string | null	否	Embedding 模型 ID
owner_agent_id	string | null	否	归属智能体 ID
user_id	string | null	否	用户 ID
session_id	string | null	否	会话 ID
source_ref	string | null	否	来源引用
importance_score	number	是	重要度
last_accessed_time	datetime | null	否	最近访问时间
expires_time	datetime | null	否	过期时间
archived_time	datetime | null	否	归档时间
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

3.9 Team

Team

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

TeamMember

Team 与 Agent 成员关系必须通过该中间表维护。Team 主表和 Team DTO 不保存成员数组。

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

TeamPolicy

字段	类型	必填	说明
max_rounds	integer	是	最大轮次
handoff	"supervisor" | "round_robin" | "auto"	是	交接策略
failure_mode	"stop_on_critical" | "continue" | "fallback"	是	失败策略
timeout_seconds	integer	是	总超时
human_approval_policy	"never" | "before_final" | "on_risk"	是	人工审批策略

TeamRun

字段	类型	必填	说明
id	string	是	团队运行 ID
team_id	string	是	团队 ID
session_id	string | null	否	会话 ID
input_text	string | null	否	输入文本
input	object | null	否	结构化输入
output_text	string | null	否	输出文本
output	object | null	否	结构化输出
status	"queued" | "running" | "completed" | "failed" | "cancelled" | "paused"	是	运行状态
created_time	datetime	是	创建时间
started_time	datetime | null	否	开始时间
finished_time	datetime | null	否	结束时间

3.10 Runtime and Observability

WorkflowRun

字段	类型	必填	说明
id	string	是	运行 ID
app_id	string	是	应用 ID
workflow_id	string	是	工作流 ID
session_id	string | null	否	会话 ID
parent_run_id	string | null	否	父运行 ID
root_run_id	string | null	否	根运行 ID
run_type	string	是	运行类型
status	"pending" | "running" | "completed" | "failed" | "cancelled" | "paused"	是	运行状态
trigger_type	string	是	触发方式
priority	integer	是	优先级
current_node_count	integer	是	当前节点数量
started_time	datetime | null	否	开始时间
finished_time	datetime | null	否	结束时间
created_time	datetime	是	创建时间

NodeRun

字段	类型	必填	说明
id	string	是	节点运行 ID
run_id	string	是	运行 ID
node_id	string	是	节点 ID
node_type	string	是	节点类型
attempt_no	integer	是	第几次尝试
status	"pending" | "queued" | "running" | "completed" | "failed" | "skipped"	是	状态
output_text	string | null	否	输出文本
output	object | null	否	结构化输出
scheduled_time	datetime | null	否	计划时间
timeout_time	datetime | null	否	超时时间
queued_time	datetime | null	否	排队时间
created_time	datetime	是	创建时间

ExecutionLog

字段	类型	必填	说明
id	string	是	日志 ID
run_id	string	是	运行 ID
node_run_id	string | null	否	节点运行 ID
event_type	string	是	事件类型
level	"debug" | "info" | "warning" | "error"	是	级别
message	string	是	日志内容
detail	object | null	否	详情
created_time	datetime	是	创建时间

TraceSpan

字段	类型	必填	说明
id	string	是	Span ID
run_id	string	是	运行 ID
node_run_id	string | null	否	节点运行 ID
parent_span_id	string | null	否	父 Span ID
span_type	string	是	Span 类型
name	string	是	名称
status	string	是	状态
started_time	datetime	是	开始时间
ended_time	datetime | null	否	结束时间
duration_ms	integer | null	否	耗时
attributes	object | null	否	属性
error_message	string | null	否	错误消息
created_time	datetime	是	创建时间

4. API 明细

下面所有接口的 Method 都是 POST。输出均使用统一响应包，表格中的“输出”指 data 字段。

4.1 Auth

接口	输入参数	输出	说明
POST /auth/login	username:string 必填；password:string 必填	access_token:string；token_type:"bearer"；expires_time:datetime；user:User	登录
POST /auth/logout	无	ok:boolean	退出登录，服务端可加入 token 黑名单
POST /auth/me	无	user:User；roles:Role[]；permissions:string[]	获取当前用户
POST /auth/users/list	PageRequest	PageResult<User>	用户列表
POST /auth/roles/list	PageRequest	PageResult<Role>	角色列表
POST /auth/roles/permissions/list	PageRequest；role_id:string 必填	PageResult<RolePermissionBinding>	查询角色权限绑定
POST /auth/roles/permissions/add	role_id:string 必填；permission:string 必填；`scope_type:string	null；scope_id:string	null`
POST /auth/roles/permissions/remove	binding_id:string 必填	deleted:boolean；binding_id:string	删除角色权限绑定
POST /auth/permissions/check	user_id:string 必填；permission:string 必填；`scope_type:string	null；scope_id:string	null`

4.2 Dashboard and Health

接口	输入参数	输出	说明
POST /dashboard/summary	`time_range:"24h"	"7d"	"30d"默认7d`
POST /health/get	无	service:string；status:string；`database:string	null；checked_time:datetime`
POST /health/services	无	service:string；status:string；`downstream_services:Array<{service:string,status:string,url:string,http_status:integer	null,error_message:string

4.3 Models

接口	输入参数	输出	说明
POST /models/list	PageRequest；`provider_type:string	null；capability:string	null`
POST /models/get	model_id:string 必填	Model	模型详情
POST /models/create	name:string 必填；provider_type:string 必填；provider_base_url:string 必填；`provider_api_key:string	null；model_name:string必填；capabilities:string[]；context_window:integer	null；max_output_tokens:integer
POST /models/update	model_id:string 必填；其余字段同 create，均可选	Model	更新模型配置
POST /models/delete	model_id:string 必填	deleted:boolean；model_id:string	删除模型配置
POST /models/test	model_id:string 必填；prompt:string 必填；`system_prompt:string	null；temperature:number	null；max_tokens:integer
POST /models/discover	provider_type:string 必填；provider_base_url:string 必填；`provider_api_key:string	null`	`models:Array<{model_name:string,display_name:string,capabilities:string[],context_window:integer

4.4 Agents

接口	输入参数	输出	说明
POST /agents/list	PageRequest；`owner_user_id:string	null；skill_id:string	null；model_id:string
POST /agents/get	agent_id:string 必填	Agent	智能体详情
POST /agents/create	name:string 必填；`owner_user_id:string	null；model_id:string	null；system_prompt:string；memory_policy:AgentMemoryPolicy；runtime_policy:AgentRuntimePolicy；metadata:object`
POST /agents/update	agent_id:string 必填；`name:string	null；model_id:string	null；system_prompt:string
POST /agents/delete	agent_id:string 必填；delete_runs:boolean 默认 false	deleted:boolean；agent_id:string	删除智能体
POST /agents/skills/list	PageRequest；agent_id:string 必填	PageResult<AgentSkillBinding>	查询智能体技能绑定
POST /agents/skills/add	agent_id:string 必填；skill_id:string 必填；`order_index:integer	null；config:object`	AgentSkillBinding
POST /agents/skills/update	binding_id:string 必填；`order_index:integer	null；config:object	null`
POST /agents/skills/remove	binding_id:string 必填	deleted:boolean；binding_id:string	删除智能体技能绑定
POST /agents/skills/reorder	agent_id:string 必填；items:Array<{binding_id:string,order_index:integer}> 必填	PageResult<AgentSkillBinding>	调整智能体技能顺序
POST /agents/runs/list	PageRequest；`agent_id:string	null；session_id:string	null；status:string
POST /agents/runs/start	agent_id:string 必填；`session_id:string	null；input_text:string	null；input:object
POST /agents/runs/get	run_id:string 必填	AgentRun	运行详情
POST /agents/runs/poll	run_id:string 必填；`after_time:datetime	null`	run:AgentRun；messages:Message[]；logs:ExecutionLog[]；`tool_calls:Array<{id:string,skill_id:string
POST /agents/runs/cancel	run_id:string 必填；`reason:string	null`	AgentRun

4.5 Sessions

接口	输入参数	输出	说明
POST /sessions/list	PageRequest；`app_id:string	null；user_id:string	null；channel_type:string
POST /sessions/get	session_id:string 必填	Session	会话详情
POST /sessions/create	app_id:string 必填；user_id:string 必填；channel_type:string 默认 web；`title:string	null`	Session
POST /sessions/messages/list	PageRequest；session_id:string 必填；`after_time:datetime	null`	PageResult<Message>
POST /sessions/messages/send	session_id:string 必填；content_text:string 必填；`content_type:"text"	"markdown"默认text；agent_id:string	null；workflow_id:string
POST /sessions/run-requests/list	PageRequest；session_id:string 必填	PageResult<RunRequest>	会话运行请求
POST /sessions/context/get	session_id:string 必填	session:Session；message_count:integer；run_count:integer；recent_run_requests:RunRequest[]	右侧上下文弹窗

4.6 MCP Tools

接口	输入参数	输出	说明
POST /tools/mcp/list	PageRequest；`keyword:string	null`	PageResult<McpServer>
POST /tools/mcp/get	mcp_server_id:string 必填	server:McpServer；tools:McpTool[]	MCP 服务详情
POST /tools/mcp/import-config	config:object 必填，格式为 {server_name:{url,headers,timeout,sse_read_timeout}}；test_connection:boolean 默认 true；discover_tools:boolean 默认 true	servers:McpServer[]；test_results:ConnectionTestResult[]；discovered_tools:McpTool[]	支持用户粘贴 MCP JSON 配置
POST /tools/mcp/create	name:string 必填；transport:string 默认 sse；`url:string	null；headers:object；timeout_seconds:integer；sse_read_timeout_seconds:integer	null`
POST /tools/mcp/update	mcp_server_id:string 必填；`name:string	null；url:string	null；headers:object
POST /tools/mcp/delete	mcp_server_id:string 必填	deleted:boolean；mcp_server_id:string	删除 MCP 服务
POST /tools/mcp/test	`mcp_server_id:string	null；name:string	null；transport:string
POST /tools/mcp/discover	mcp_server_id:string 必填；refresh:boolean 默认 true	mcp_server_id:string；tools:McpTool[]；discovered_time:datetime	发现 MCP 内部工具
POST /tools/mcp/tools/list	PageRequest；`mcp_server_id:string	null`	PageResult<McpTool>
POST /tools/mcp/tools/get	tool_id:string 必填	McpTool	工具参数详情

4.7 Skills

接口	输入参数	输出	说明
POST /skills/list	PageRequest；`category:string	null；tool_id:string	null`
POST /skills/get	skill_id:string 必填	Skill	技能详情
POST /skills/create	name:string 必填；category:string 必填；`description:string	null；instruction:string必填；parameter_schema:object；output_schema:object；metadata:object`	Skill
POST /skills/update	skill_id:string 必填；其余字段同 create，均可选	Skill	编辑技能，工具绑定通过中间表 API 独立维护
POST /skills/delete	skill_id:string 必填	deleted:boolean；skill_id:string	删除技能
POST /skills/tools/list	PageRequest；skill_id:string 必填	PageResult<SkillToolBinding>	查询技能工具绑定
POST /skills/tools/add	skill_id:string 必填；tool_id:string 必填；`order_index:integer	null；parameter_mapping:object；config:object`	SkillToolBinding
POST /skills/tools/update	binding_id:string 必填；`order_index:integer	null；parameter_mapping:object	null；config:object
POST /skills/tools/remove	binding_id:string 必填	deleted:boolean；binding_id:string	删除技能工具绑定
POST /skills/tools/reorder	skill_id:string 必填；items:Array<{binding_id:string,order_index:integer}> 必填	PageResult<SkillToolBinding>	调整技能工具顺序
POST /skills/installations/list	PageRequest；`skill_id:string	null；install_scope:string	null；scope_id:string
POST /skills/install	skill_id:string 必填；install_scope:string 必填；`scope_id:string	null；config:object`	SkillInstallation
POST /skills/uninstall	installation_id:string 必填	deleted:boolean；installation_id:string	卸载技能
POST /skills/test	skill_id:string 必填；input:object 必填；`agent_id:string	null；session_id:string	null`

4.8 Knowledge

接口	输入参数	输出	说明
POST /knowledge/bases/list	PageRequest；include_archived:boolean 默认 false	PageResult<KnowledgeBase>	知识库列表页
POST /knowledge/bases/get	knowledge_base_id:string 必填	KnowledgeBase	知识库详情
POST /knowledge/bases/create	name:string 必填；`description:string	null；settings:KnowledgeSettings	null；metadata:object`
POST /knowledge/bases/update	knowledge_base_id:string 必填；`name:string	null；description:string	null；metadata:object
POST /knowledge/bases/archive	knowledge_base_id:string 必填	KnowledgeBase	归档知识库
POST /knowledge/bases/restore	knowledge_base_id:string 必填	KnowledgeBase	恢复知识库
POST /knowledge/settings/get	knowledge_base_id:string 必填	KnowledgeSettings	获取检索设置
POST /knowledge/settings/save	knowledge_base_id:string 必填；settings:KnowledgeSettings 必填	KnowledgeSettings	保存设置，必须支持 Rerank 模型
POST /knowledge/documents/list	PageRequest；knowledge_base_id:string 必填；`source_type:string	null；index_status:string	null`
POST /knowledge/documents/parse	source_type:string 必填；`source_uri:string	null；content_text:string	null；content_base64:string
POST /knowledge/documents/create	knowledge_base_id:string 必填；title:string 必填；source_type:string 必填；`source_uri:string	null；content_text:string	null；content_base64:string
POST /knowledge/documents/delete	document_id:string 必填	deleted:boolean；document_id:string	删除文档
POST /knowledge/documents/reindex	document_id:string 必填；`settings:KnowledgeSettings	null`	KnowledgeJob
POST /knowledge/search	knowledge_base_id:string 必填；query:string 必填；top_k:integer 默认 5；filters:object；`rerank_model_id:string	null；include_score_detail:boolean默认true`	KnowledgeSearchResult[]
POST /knowledge/jobs/list	PageRequest；`knowledge_base_id:string	null；document_id:string	null；status:string
POST /knowledge/jobs/create	knowledge_base_id:string 必填；`document_id:string	null；job_type:string必填；payload:object`	KnowledgeJob
POST /knowledge/jobs/retry	job_id:string 必填	KnowledgeJob	重试任务
POST /knowledge/jobs/cancel	job_id:string 必填；`reason:string	null`	KnowledgeJob
POST /knowledge/evals/list	PageRequest；knowledge_base_id:string 必填	`PageResult<{id:string,knowledge_base_id:string,query:string,expected:string,recall:number,precision:number,last_run_time:datetime	null,created_time:datetime}>`
POST /knowledge/evals/create	knowledge_base_id:string 必填；query:string 必填；expected:string 必填	id:string；knowledge_base_id:string；query:string；expected:string；created_time:datetime	新增评估问题
POST /knowledge/evals/run	knowledge_base_id:string 必填；`eval_ids:string[]	null`	job:KnowledgeJob

4.9 Memories

接口	输入参数	输出	说明
POST /memories/list	PageRequest；`scope_type:string	null；scope_id:string	null；memory_type:string
POST /memories/get	memory_id:string 必填	MemoryItem	记忆详情
POST /memories/search	query:string 必填；`scope_type:string	null；scope_id:string	null；owner_agent_id:string
POST /memories/create	scope_type:string 必填；scope_id:string 必填；memory_type:string 必填；content_text:string 必填；`content:object	null；metadata:object；owner_agent_id:string	null；user_id:string
POST /memories/archive	memory_id:string 必填	MemoryItem	归档记忆
POST /memories/delete	memory_id:string 必填	deleted:boolean；memory_id:string	删除记忆

4.10 Teams

接口	输入参数	输出	说明
POST /teams/list	PageRequest；`owner_user_id:string	null；agent_id:string	null`
POST /teams/get	team_id:string 必填	Team	团队详情
POST /teams/create	name:string 必填；`description:string	null；owner_user_id:string	null；coordination_mode:string；objective:string
POST /teams/update	team_id:string 必填；其余字段同 create，均可选	Team	编辑团队，成员绑定通过中间表 API 独立维护
POST /teams/delete	team_id:string 必填；delete_runs:boolean 默认 false	deleted:boolean；team_id:string	删除团队
POST /teams/members/list	PageRequest；team_id:string 必填	PageResult<TeamMember>	查询团队成员绑定
POST /teams/members/add	team_id:string 必填；agent_id:string 必填；role:string 必填；`responsibility:string	null；order_index:integer	null；config:object`
POST /teams/members/update	member_id:string 必填；`role:string	null；responsibility:string	null；order_index:integer
POST /teams/members/remove	member_id:string 必填	deleted:boolean；member_id:string	删除团队成员
POST /teams/members/reorder	team_id:string 必填；items:Array<{member_id:string,order_index:integer}> 必填	PageResult<TeamMember>	调整团队成员顺序
POST /teams/runs/list	PageRequest；`team_id:string	null；session_id:string	null；status:string
POST /teams/runs/start	team_id:string 必填；`session_id:string	null；input_text:string	null；input:object
POST /teams/runs/get	run_id:string 必填	TeamRun	团队运行详情
POST /teams/runs/cancel	run_id:string 必填；`reason:string	null`	TeamRun

4.11 Runtime and Logs

接口	输入参数	输出	说明
POST /runtime/runs/list	PageRequest；`app_id:string	null；workflow_id:string	null；session_id:string
POST /runtime/runs/get	run_id:string 必填	WorkflowRun	运行详情
POST /runtime/node-runs/list	PageRequest；run_id:string 必填；`status:string	null`	PageResult<NodeRun>
POST /runtime/execution-logs/list	PageRequest；run_id:string 必填；`node_run_id:string	null；level:string	null`
POST /runtime/trace-spans/list	PageRequest；run_id:string 必填；`node_run_id:string	null`	PageResult<TraceSpan>

4.12 Settings and API Keys

接口	输入参数	输出	说明
POST /api-keys/list	PageRequest	PageResult<ApiKey>	API Key 列表
POST /api-keys/create	name:string 必填；`scopes:string	null；expires_time:datetime	null`
POST /api-keys/revoke	api_key_id:string 必填	ApiKey	撤销 API Key

ApiKey

字段	类型	必填	说明
id	string	是	API Key ID
name	string	是	名称
key_prefix	string	是	前缀
revoked_time	datetime | null	否	撤销时间
scopes	string | null	否	权限范围
expires_time	datetime | null	否	过期时间
last_used_time	datetime | null	否	最近使用时间
created_time	datetime	是	创建时间

ApiKeyCreated = ApiKey 加上以下字段：

字段	类型	必填	说明
api_key	string	是	明文密钥，仅创建后返回一次

4.13 Workflow Designer and Debugger

当前前端未挂 Workflow 路由，但平台需要多应用、多智能体、团队模式，建议保留以下 API，后续用于设计器和调试器闭环。

Workflow

字段	类型	必填	说明
id	string	是	工作流 ID
app_id	string	是	应用 ID
name	string	是	名称
workflow_type	string	是	类型
dsl	WorkflowDSL	是	设计器 DSL
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

WorkflowDSL

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

WorkflowNode

字段	类型	必填	说明
id	string	是	节点 ID
type	string	是	节点类型
name	string | null	否	展示名称
config	object	是	节点配置

WorkflowEdge

字段	类型	必填	说明
source	string	是	来源节点 ID
target	string	是	目标节点 ID
condition	string | null	否	条件表达式

接口	输入参数	输出	说明
POST /workflows/list	PageRequest；`app_id:string	null；workflow_type:string	null`
POST /workflows/get	workflow_id:string 必填	Workflow	工作流详情
POST /workflows/create	app_id:string 必填；name:string 必填；workflow_type:string 必填；dsl:WorkflowDSL	Workflow	新建工作流
POST /workflows/save	workflow_id:string 必填；`name:string	null；dsl:WorkflowDSL` 必填	Workflow
POST /workflows/delete	workflow_id:string 必填	deleted:boolean；workflow_id:string	删除工作流
POST /workflows/validate	dsl:WorkflowDSL 必填	valid:boolean；`diagnostics:Array<{severity:string,diagnostic_id:string,message:string,node_id:string	null,edge_index:integer
POST /workflows/debug/start	`workflow_id:string	null；dsl:WorkflowDSL	null；input:object；breakpoints:string[]`
POST /workflows/debug/step	debug_session_id:string 必填；`action:"next"	"continue"	"pause"必填；input_patch:object
POST /workflows/debug/stop	debug_session_id:string 必填	stopped:boolean；finished_time:datetime	停止调试

4.14 Apps

接口	输入参数	输出	说明
POST /apps/list	PageRequest	PageResult<App>	应用列表
POST /apps/create	name:string 必填；`description:string	null；owner_user_id:string	null；settings:object`
POST /apps/update	app_id:string 必填；`name:string	null；description:string	null；settings:object
POST /apps/delete	app_id:string 必填	deleted:boolean；app_id:string	删除应用

App

字段	类型	必填	说明
id	string	是	应用 ID
name	string	是	应用名
description	string | null	否	说明
owner_user_id	string | null	否	创建人
settings	object	是	应用设置
created_time	datetime	是	创建时间
updated_time	datetime	是	更新时间

5. 前端迁移清单

优先级	任务	说明
P0	API Client 改造	apiClient.get/patch/delete 全部迁移为 post，路径改为动作式 /list、/update、/delete
P0	类型清理	前端类型删除 version_no、agent_type、team_type、enabled、直接 *_json 字段
P0	Agent 真实运行	替换本地模拟 AgentRuns，接入 /agents/runs/start、/poll、/cancel
P0	MCP 闭环	工具页支持粘贴 MCP JSON、连接测试、发现工具、展示参数说明
P1	Skills 接真实 API	当前 Skills 页仍是 mock，需要接 /skills/*
P1	Knowledge mock 落库	Jobs、Evaluation、Settings 需要接真实 API
P1	Teams 去版本化	团队配置合并到 Team，前端不排序 version_no
P1	Memory 展示收敛	继续避免 raw JSON，详情改成业务字段卡片
P2	Workflow 设计器	挂路由并接入校验、调试 API
P2	可观测性深度	Dashboard 增加 trace、节点耗时、错误聚合