# 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` | `agentCount:integer`；`sessionCount:integer`；`runCount:integer`；`failedRunCount:integer`；`liveRunCount:integer`；`healthyServiceCount:integer`；`trend:Array<{date:string,total:integer,successful:integer,failed:integer}>` | 仪表盘聚合 |
| `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|null}>` | 下游服务健康 |

### 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` | `RolePermissionBinding` | 新增角色权限绑定 |
| `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` | `allowed:boolean`；`reason:string`；`matchedRoleIds:string[]` | 权限检查 |
| `POST /gateway/identity/apiKeys/list` | `PageRequest` | `PageResult<ApiKey>` | API Key 列表 |
| `POST /gateway/identity/apiKeys/create` | `name:string` 必填；`scopes:string|null`；`expiresTime:datetime|null` | `apiKey:ApiKey`；`secret:string` | 创建 API Key，明文只返回一次 |
| `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` | `PageResult<Model>` | 模型列表 |
| `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|null`；`defaultTemperature:number|null`；`timeoutSeconds:integer`；`metadata:object` | `Model` | 新建模型 |
| `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|null` | `ModelTestResult` | 测试模型 |
| `POST /gateway/model/models/discover` | `providerType:string` 必填；`providerBaseUrl:string` 必填；`providerApiKey:string|null` | `models:Array<{modelName:string,displayName:string,capabilities:string[],contextWindow:integer|null}>` | 自动发现模型 |

### 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` | `McpServer` | 创建 MCP 服务 |
| `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|null`；`url:string|null`；`headers:object|null`；`timeoutSeconds:integer|null`；`sseReadTimeoutSeconds:integer|null` | `ConnectionTestResult` | 测试连接 |
| `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>` | MCP 内部工具列表 |
| `POST /gateway/tool/mcpTools/get` | `toolId:string` 必填 | `McpTool` | MCP 内部工具详情 |

### 5.5 skillService

| 接口 | 输入参数 | 输出 | 说明 |
| --- | --- | --- | --- |
| `POST /gateway/skill/skills/list` | `PageRequest`；`category:string|null`；`toolId:string|null` | `PageResult<Skill>` | 技能列表 |
| `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|null` | `SkillToolBinding` | 更新技能工具绑定 |
| `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|null` | `PageResult<SkillInstallation>` | 技能安装列表 |
| `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` | `output:object`；`logs:object[]`；`latencyMs:integer` | 测试技能 |

`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|null` | `PageResult<Agent>` | 智能体列表 |
| `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` | `Agent` | 创建智能体，不包含技能数组 |
| `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` | `AgentSkillBinding` | 更新智能体技能绑定 |
| `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|null`；`startTime:datetime|null`；`endTime:datetime|null` | `PageResult<AgentRun>` | 运行历史 |
| `POST /gateway/agent/agentRuns/start` | `agentId:string` 必填；`sessionId:string|null`；`inputText:string|null`；`input:object|null`；`stream:boolean` 默认 `false` | `AgentRun` | 启动智能体运行 |
| `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|null,toolId:string|null,name:string,input:object,output:object|null,status:string,startedTime:datetime|null,finishedTime:datetime|null}>` | 轮询运行进度 |
| `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|null` | `PageResult<Session>` | 会话列表 |
| `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|null`；`triggerRun:boolean` 默认 `true` | `message:Message`；`runRequest:RunRequest|null` | 发送消息并可触发运行 |
| `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` | `KnowledgeBase` | 创建知识库 |
| `POST /gateway/knowledge/bases/update` | `knowledgeBaseId:string` 必填；`name:string|null`；`description:string|null`；`metadata:object|null` | `KnowledgeBase` | 更新知识库 |
| `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` | `PageResult<KnowledgeDocument>` | 文档列表 |
| `POST /gateway/knowledge/documents/parse` | `sourceType:string` 必填；`sourceUri:string|null`；`contentText:string|null`；`contentBase64:string|null`；`fileName:string|null` | `contentText:string`；`sourceType:string`；`metadata:object` | 文档解析预览 |
| `POST /gateway/knowledge/documents/create` | `knowledgeBaseId:string` 必填；`title:string` 必填；`sourceType:string` 必填；`sourceUri:string|null`；`contentText:string|null`；`contentBase64:string|null`；`metadata:object`；`chunkSize:integer|null`；`chunkOverlap:integer|null` | `document:KnowledgeDocument`；`chunks:KnowledgeChunk[]`；`job:object|null` | 导入文档 |
| `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|null}>` | 检索测试 |
| `POST /gateway/knowledge/jobs/list` | `PageRequest`；`knowledgeBaseId:string|null`；`documentId:string|null`；`status:string|null` | `PageResult<object>` | 索引任务 |
| `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|null`；`ownerAgentId:string|null`；`userId:string|null`；`sessionId:string|null` | `PageResult<MemoryItem>` | 记忆列表 |
| `POST /gateway/memory/memories/get` | `memoryId:string` 必填 | `MemoryItem` | 记忆详情 |
| `POST /gateway/memory/memories/search` | `query:string` 必填；`scopeType:string|null`；`scopeId:string|null`；`ownerAgentId:string|null`；`userId:string|null`；`sessionId:string|null`；`limit:integer` 默认 10 | `items:Array<{item:MemoryItem,score:number,scoreDetail:object}>` | 语义搜索 |
| `POST /gateway/memory/memories/create` | `scopeType:string` 必填；`scopeId:string` 必填；`memoryType:string` 必填；`contentText:string` 必填；`content:object|null`；`metadata:object`；`ownerAgentId:string|null`；`userId:string|null`；`sessionId:string|null`；`sourceRef:string|null`；`importanceScore:number`；`expiresTime:datetime|null` | `MemoryItem` | 系统内部写入记忆 |
| `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` | `PageResult<Team>` | 团队列表 |
| `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|null`；`policy:TeamPolicy`；`metadata:object` | `Team` | 创建团队，不包含成员数组 |
| `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` | `TeamMember` | 新增团队成员 |
| `POST /gateway/team/teamMembers/update` | `memberId:string` 必填；`role:string|null`；`responsibility:string|null`；`orderIndex:integer|null`；`config:object|null` | `TeamMember` | 更新团队成员 |
| `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|null`；`startTime:datetime|null`；`endTime:datetime|null` | `PageResult<TeamRun>` | 团队运行列表 |
| `POST /gateway/team/teamRuns/start` | `teamId:string` 必填；`sessionId:string|null`；`inputText:string|null`；`input:object|null` | `TeamRun` | 启动团队运行 |
| `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` | `App` | 创建应用 |
| `POST /gateway/workflow/apps/update` | `appId:string` 必填；`name:string|null`；`description:string|null`；`settings:object|null` | `App` | 更新应用 |
| `POST /gateway/workflow/apps/delete` | `appId:string` 必填 | `deleted:boolean`；`appId:string` | 删除应用 |
| `POST /gateway/workflow/workflows/list` | `PageRequest`；`appId:string|null`；`workflowType:string|null` | `PageResult<Workflow>` | 工作流列表 |
| `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|null}>`；`nodeCount:integer`；`edgeCount:integer`；`entryNodeIds:string[]`；`terminalNodeIds:string[]`；`isolatedNodeIds:string[]`；`unreachableNodeIds:string[]`；`cycleDetected:boolean` | 校验工作流 |
| `POST /gateway/workflow/debug/start` | `workflowId:string|null`；`dsl:WorkflowDsl|null`；`input:object`；`breakpoints:string[]` | `debugSessionId:string`；`runId:string`；`createdTime:datetime` | 启动调试 |
| `POST /gateway/workflow/debug/step` | `debugSessionId:string` 必填；`action:"next"|"continue"|"pause"` 必填；`inputPatch:object|null` | `run:WorkflowRun`；`currentNode:NodeRun|null`；`logs: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|null`；`status:string|null`；`startTime:datetime|null`；`endTime:datetime|null` | `PageResult<WorkflowRun>` | 运行列表 |
| `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` | `PageResult<object>` | 执行日志 |
| `POST /gateway/runtime/traceSpans/list` | `PageRequest`；`runId:string` 必填；`nodeRunId:string|null` | `PageResult<object>` | Trace 数据 |

## 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 |