# 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` | `RolePermissionBinding` | 新增角色权限绑定 |
| `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` | `allowed:boolean`；`reason:string`；`matched_role_ids:string[]` | 权限检查 |

### 4.2 Dashboard and Health

| 接口 | 输入参数 | 输出 | 说明 |
| --- | --- | --- | --- |
| `POST /dashboard/summary` | `time_range:"24h"|"7d"|"30d"` 默认 `7d` | `agent_count:integer`；`session_count:integer`；`run_count:integer`；`failed_run_count:integer`；`live_run_count:integer`；`healthy_service_count:integer`；`trend:Array<{date:string,total:integer,successful:integer,failed:integer}>` | 仪表盘聚合，减少前端多次请求 |
| `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|null}>` | 下游服务健康 |

### 4.3 Models

| 接口 | 输入参数 | 输出 | 说明 |
| --- | --- | --- | --- |
| `POST /models/list` | `PageRequest`；`provider_type:string|null`；`capability:string|null` | `PageResult<Model>` | 模型配置列表 |
| `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|null`；`default_temperature:number|null`；`timeout_seconds:integer`；`metadata:object` | `Model` | 新增模型配置 |
| `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|null` | `ModelTestResult` | 测试模型 |
| `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|null}>` | 自动发现供应商模型，可合并到新建弹窗 |

### 4.4 Agents

| 接口 | 输入参数 | 输出 | 说明 |
| --- | --- | --- | --- |
| `POST /agents/list` | `PageRequest`；`owner_user_id:string|null`；`skill_id:string|null`；`model_id:string|null` | `PageResult<Agent>` | 智能体列表 |
| `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` | `Agent` | 新建智能体，不传类型、状态、版本、技能 ID 数组 |
| `POST /agents/update` | `agent_id:string` 必填；`name:string|null`；`model_id:string|null`；`system_prompt:string|null`；`memory_policy:AgentMemoryPolicy|null`；`runtime_policy:AgentRuntimePolicy|null`；`metadata:object|null` | `Agent` | 编辑智能体，技能绑定通过中间表 API 独立维护 |
| `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` | `AgentSkillBinding` | 更新智能体技能绑定 |
| `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|null`；`start_time:datetime|null`；`end_time:datetime|null` | `PageResult<AgentRun>` | 运行历史 |
| `POST /agents/runs/start` | `agent_id:string` 必填；`session_id:string|null`；`input_text:string|null`；`input:object|null`；`stream:boolean` 默认 `false` | `AgentRun` | 启动真实智能体执行 |
| `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|null,tool_id:string|null,name:string,input:object,output:object|null,status:string,started_time:datetime|null,finished_time:datetime|null}>` | POST 轮询运行进度 |
| `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|null` | `PageResult<Session>` | 会话列表 |
| `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|null`；`trigger_run:boolean` 默认 `true` | `message:Message`；`run_request:RunRequest|null` | 发送消息，可触发运行 |
| `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>` | MCP 服务列表 |
| `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` | `McpServer` | 表单创建 MCP 服务 |
| `POST /tools/mcp/update` | `mcp_server_id:string` 必填；`name:string|null`；`url:string|null`；`headers:object|null`；`timeout_seconds:integer|null`；`sse_read_timeout_seconds:integer|null` | `McpServer` | 更新 MCP 服务 |
| `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|null`；`url:string|null`；`headers:object|null`；`timeout_seconds:integer|null`；`sse_read_timeout_seconds:integer|null` | `ConnectionTestResult` | 测试已保存或临时连接 |
| `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>` | MCP 内部工具列表 |
| `POST /tools/mcp/tools/get` | `tool_id:string` 必填 | `McpTool` | 工具参数详情 |

### 4.7 Skills

| 接口 | 输入参数 | 输出 | 说明 |
| --- | --- | --- | --- |
| `POST /skills/list` | `PageRequest`；`category:string|null`；`tool_id:string|null` | `PageResult<Skill>` | 技能列表 |
| `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` | 创建技能，不传工具 ID 数组 |
| `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|null` | `SkillToolBinding` | 更新技能工具绑定 |
| `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|null` | `PageResult<SkillInstallation>` | 安装列表 |
| `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` | `output:object`；`logs:ExecutionLog[]`；`latency_ms:integer` | 测试技能执行 |

### 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` | `KnowledgeBase` | 新建知识库 |
| `POST /knowledge/bases/update` | `knowledge_base_id:string` 必填；`name:string|null`；`description:string|null`；`metadata:object|null` | `KnowledgeBase` | 编辑知识库基础信息 |
| `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` | `PageResult<KnowledgeDocument>` | 文档列表 |
| `POST /knowledge/documents/parse` | `source_type:string` 必填；`source_uri:string|null`；`content_text:string|null`；`content_base64:string|null`；`file_name:string|null` | `content_text:string`；`source_type:string`；`metadata:object` | 文档解析预览 |
| `POST /knowledge/documents/create` | `knowledge_base_id:string` 必填；`title:string` 必填；`source_type:string` 必填；`source_uri:string|null`；`content_text:string|null`；`content_base64:string|null`；`metadata:object`；`chunk_size:integer|null`；`chunk_overlap:integer|null` | `document:KnowledgeDocument`；`chunks:KnowledgeChunk[]`；`job:KnowledgeJob|null` | 导入文档 |
| `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|null` | `PageResult<KnowledgeJob>` | 索引任务 |
| `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|null`；`owner_agent_id:string|null`；`user_id:string|null`；`session_id:string|null` | `PageResult<MemoryItem>` | 记忆列表，主 UI 以只读为主 |
| `POST /memories/get` | `memory_id:string` 必填 | `MemoryItem` | 记忆详情 |
| `POST /memories/search` | `query:string` 必填；`scope_type:string|null`；`scope_id:string|null`；`owner_agent_id:string|null`；`user_id:string|null`；`session_id:string|null`；`limit:integer` 默认 10 | `Array<{item:MemoryItem,score:number,score_detail:object}>` | 语义搜索 |
| `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|null`；`session_id:string|null`；`source_ref:string|null`；`importance_score:number`；`expires_time:datetime|null` | `MemoryItem` | 系统内部写入记忆，前端不做主入口按钮 |
| `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` | `PageResult<Team>` | 团队列表 |
| `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|null`；`policy:TeamPolicy`；`metadata:object` | `Team` | 新建团队，不传类型、状态、版本、成员数组 |
| `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` | `TeamMember` | 新增团队成员 |
| `POST /teams/members/update` | `member_id:string` 必填；`role:string|null`；`responsibility:string|null`；`order_index:integer|null`；`config:object|null` | `TeamMember` | 更新团队成员 |
| `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|null`；`start_time:datetime|null`；`end_time:datetime|null` | `PageResult<TeamRun>` | 团队运行列表 |
| `POST /teams/runs/start` | `team_id:string` 必填；`session_id:string|null`；`input_text:string|null`；`input:object|null` | `TeamRun` | 启动团队执行 |
| `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|null`；`status:string|null`；`start_time:datetime|null`；`end_time:datetime|null` | `PageResult<WorkflowRun>` | 工作流运行 |
| `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` | `PageResult<ExecutionLog>` | 执行日志 |
| `POST /runtime/trace-spans/list` | `PageRequest`；`run_id:string` 必填；`node_run_id:string|null` | `PageResult<TraceSpan>` | Trace 数据 |

### 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` | `ApiKeyCreated` | 创建 API Key，明文只返回一次 |
| `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` | `PageResult<Workflow>` | 工作流列表 |
| `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|null}>`；`node_count:integer`；`edge_count:integer`；`entry_node_ids:string[]`；`terminal_node_ids:string[]`；`isolated_node_ids:string[]`；`unreachable_node_ids:string[]`；`cycle_detected:boolean` | 校验 DSL |
| `POST /workflows/debug/start` | `workflow_id:string|null`；`dsl:WorkflowDSL|null`；`input:object`；`breakpoints:string[]` | `debug_session_id:string`；`run_id:string`；`created_time:datetime` | 启动调试 |
| `POST /workflows/debug/step` | `debug_session_id:string` 必填；`action:"next"|"continue"|"pause"` 必填；`input_patch:object|null` | `run:WorkflowRun`；`current_node:NodeRun|null`；`logs:ExecutionLog[]` | 单步调试 |
| `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` | `App` | 新建应用 |
| `POST /apps/update` | `app_id:string` 必填；`name:string|null`；`description:string|null`；`settings:object|null` | `App` | 编辑应用 |
| `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、节点耗时、错误聚合 |