mirror of
https://github.com/chaitin/MonkeyCode.git
synced 2026-11-22 19:39:31 +08:00
11325 lines
405 KiB
YAML
11325 lines
405 KiB
YAML
openapi: 3.1.0
|
||
info:
|
||
title: MonkeyAI Admin API
|
||
version: 1.0.0
|
||
servers:
|
||
- url: /
|
||
security:
|
||
- AdminSession: []
|
||
paths:
|
||
/api/kb/{id}/assets/{name}:
|
||
get:
|
||
summary: 读取知识库正文图片
|
||
description: 支持浏览器会话或 Agent Bearer token。管理员可读取未删除库;普通用户必须拥有启用库的阅读权限。每次读取检查权限,响应 private/no-store;不接受源站 URL,始终读取该知识库对象存储目录下已校验的图片。
|
||
security: [{BrowserSession: []}, {KnowledgeAssetBearer: []}]
|
||
parameters:
|
||
- {name: id, in: path, required: true, schema: {type: string, format: uuid}}
|
||
- {name: name, in: path, required: true, schema: {type: string, pattern: '^[a-f0-9]{64}\.(png|jpg|gif|webp)$'}}
|
||
responses:
|
||
'200':
|
||
description: 原始图片二进制,PNG/JPEG/GIF/WebP
|
||
content:
|
||
image/png: {schema: {type: string, format: binary}}
|
||
image/jpeg: {schema: {type: string, format: binary}}
|
||
image/gif: {schema: {type: string, format: binary}}
|
||
image/webp: {schema: {type: string, format: binary}}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
|
||
/api/auth/v1/profile:
|
||
get:
|
||
summary: 读取本人账户设置
|
||
description: 任意有效浏览器登录会话可用。返回最终展示头像、自定义和同步头像地址、是否已设置密码,以及绑定当前 Cookie 的 CSRF 令牌。响应不缓存,不返回密码哈希。
|
||
security: [{BrowserSession: []}]
|
||
responses:
|
||
'200':
|
||
description: 本人账户设置
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/AccountProfile'}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
/api/auth/v1/profile/avatar:
|
||
put:
|
||
summary: 上传本人自定义头像
|
||
description: 请求体直接发送图片二进制,不使用 multipart。支持 JPG、PNG、WebP,最多 5 MiB、2500 万像素且单边不超过 8192 像素;服务端校验完整图片。图片保存到对象存储,仅更新 custom_avatar_url,不修改 OAuth 的 avatar_url。
|
||
security: [{BrowserSession: []}]
|
||
parameters: [{$ref: '#/components/parameters/ProfileCSRF'}]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
image/jpeg:
|
||
schema: {type: string, format: binary}
|
||
image/png:
|
||
schema: {type: string, format: binary}
|
||
image/webp:
|
||
schema: {type: string, format: binary}
|
||
responses:
|
||
'200':
|
||
description: 头像已保存
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/AvatarUpdate'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'403': {$ref: '#/components/responses/ProfileError', description: CSRF 令牌或请求来源无效}
|
||
'413': {$ref: '#/components/responses/ProfileError', description: 图片超过 5 MiB}
|
||
'503': {$ref: '#/components/responses/ProfileError', description: 头像存储不可用}
|
||
delete:
|
||
summary: 清除本人自定义头像
|
||
description: 仅清空 custom_avatar_url,重新显示最新 OAuth 同步头像;同步头像也为空时使用默认头像。旧上传对象在事务提交后尽力清理。
|
||
security: [{BrowserSession: []}]
|
||
parameters: [{$ref: '#/components/parameters/ProfileCSRF'}]
|
||
responses:
|
||
'200':
|
||
description: 已恢复同步头像或默认头像
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/AvatarUpdate'}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'403': {$ref: '#/components/responses/ProfileError', description: CSRF 令牌或请求来源无效}
|
||
/api/auth/v1/profile/password:
|
||
post:
|
||
summary: 修改本人登录密码
|
||
description: 必须正确提供当前密码;未设置密码的 OAuth 账号应通过现有验证码重置流程设置密码。新密码至少 12 个 Unicode 字符、最多 1024 字节,且不能与当前密码相同。每个用户每 15 分钟最多 10 次有效格式的校验请求。成功时在同一事务中更新密码、撤销旧浏览器会话、OAuth 授权和令牌、未兑换授权码、已批准但尚未兑换的设备授权及登录/重置验证码,并创建当前浏览器的新会话;同时更新 Cookie 和 CSRF 令牌。原密码、明文新密码及哈希均不进入审计参数或响应。
|
||
security: [{BrowserSession: []}]
|
||
parameters: [{$ref: '#/components/parameters/ProfileCSRF'}]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [current_password, new_password]
|
||
properties:
|
||
current_password: {type: string, minLength: 1, maxLength: 1024}
|
||
new_password: {type: string, minLength: 12, maxLength: 1024}
|
||
responses:
|
||
'200':
|
||
description: 密码已修改,当前浏览器会话已轮换
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [csrf_token]
|
||
properties:
|
||
csrf_token: {type: string}
|
||
'400': {$ref: '#/components/responses/ProfileError', description: 密码格式无效、未设置密码或新旧密码相同}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'403': {$ref: '#/components/responses/ProfileError', description: 当前密码、CSRF 令牌或请求来源无效}
|
||
'409': {$ref: '#/components/responses/ProfileError', description: 校验期间密码或设备授权发生并发变化,需重新提交;本次事务未修改密码}
|
||
'429': {$ref: '#/components/responses/ProfileError', description: 密码校验次数已达上限,返回 Retry-After}
|
||
/api/auth/v1/avatars/{userID}/{avatarID}:
|
||
get:
|
||
summary: 读取用户当前自定义头像
|
||
description: 图片地址包含随机 UUID 版本,不需要登录 Cookie,以供浏览器和客户端展示头像。只提供用户当前自定义头像,已替换或清除的版本返回 404;响应支持 ETag 和缓存。
|
||
security: []
|
||
parameters:
|
||
- {name: userID, in: path, required: true, schema: {type: string, format: uuid}}
|
||
- {name: avatarID, in: path, required: true, schema: {type: string, format: uuid}}
|
||
responses:
|
||
'200':
|
||
description: 头像图片
|
||
content:
|
||
image/jpeg:
|
||
schema: {type: string, format: binary}
|
||
image/png:
|
||
schema: {type: string, format: binary}
|
||
image/webp:
|
||
schema: {type: string, format: binary}
|
||
'304': {description: 图片未改变}
|
||
'404': {description: 用户或头像版本不存在, content: {text/plain: {schema: {type: string}}}}
|
||
'503': {$ref: '#/components/responses/ProfileError', description: 头像存储不可用}
|
||
/api/admin/v1/resource-import-uploads:
|
||
post:
|
||
summary: 创建资源包上传会话
|
||
description: 仅管理员可用,会话与创建者绑定,有效期 24 小时,每人最多 5 个未完成任务。普通 ZIP 或按字节拆分的 .zip.001 等分卷按顺序组成一个 ZIP,总大小不超过 2 GiB,最多 256 卷;不支持 .z01 或 7z 分卷。网络上传统一使用 64 MiB 传输块。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [files]
|
||
properties:
|
||
files:
|
||
type: array
|
||
minItems: 1
|
||
maxItems: 256
|
||
items: {$ref: '#/components/schemas/ResourceImportUploadFile'}
|
||
responses:
|
||
'201':
|
||
description: 返回上传会话
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ResourceImportUpload'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'409': {description: 未完成任务数已达上限}
|
||
get:
|
||
summary: 查询当前管理员未完成的资源包上传任务
|
||
responses:
|
||
'200':
|
||
description: 返回尚未过期的 uploading 和 ready 任务
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [items]
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ResourceImportUpload'}
|
||
/api/admin/v1/resource-import-uploads/{id}:
|
||
parameters:
|
||
- {name: id, in: path, required: true, schema: {type: string, format: uuid}}
|
||
get:
|
||
summary: 查询上传进度及已保存的传输块
|
||
responses:
|
||
'200':
|
||
description: 刷新页面或重启服务后可据此续传;本地文件须重新选择并核对已上传块摘要
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ResourceImportUpload'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
delete:
|
||
summary: 放弃未完成上传任务
|
||
description: 使任务立即失效,后台定期清理暂存对象;已导入任务不能取消。
|
||
responses:
|
||
'204': {description: 任务已取消}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'409': {description: 任务已导入}
|
||
/api/admin/v1/resource-import-uploads/{id}/chunks/{index}:
|
||
put:
|
||
summary: 上传一个资源包传输块
|
||
description: index 从 0 开始,对应逻辑 ZIP 的 index × chunk_size 偏移;除末块外必须恰好 64 MiB。服务端核对实际大小和 SHA-256,同内容重复上传幂等,不同内容或已封存返回 409。分块可乱序上传。
|
||
parameters:
|
||
- {name: id, in: path, required: true, schema: {type: string, format: uuid}}
|
||
- {name: index, in: path, required: true, schema: {type: integer, minimum: 0, maximum: 31}}
|
||
- {name: X-Content-SHA256, in: header, required: true, schema: {type: string, pattern: '^sha256:[0-9a-f]{64}$'}}
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/octet-stream:
|
||
schema: {type: string, format: binary}
|
||
responses:
|
||
'204': {description: 传输块已保存或同内容已存在}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'409': {description: 块内容冲突或上传已封存}
|
||
/api/admin/v1/resource-import-uploads/{id}/complete:
|
||
post:
|
||
summary: 检查完整 ZIP 并封存上传内容
|
||
description: 收齐所有传输块后检查 ZIP 路径、展开限制及外层文件 CRC,计算完整 ZIP 的 package_sha256。成功后 ready 状态不可修改,重复完成幂等。本接口不导入资源,也不校验包内声明的发布协议摘要。
|
||
parameters:
|
||
- {name: id, in: path, required: true, schema: {type: string, format: uuid}}
|
||
responses:
|
||
'200':
|
||
description: 完整上传会话
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ResourceImportUpload'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
/api/admin/v1/resource-imports/preview:
|
||
post:
|
||
summary: 解析资源发布包并预览变更
|
||
description: 使用封存的 upload_id 或不超过2 GiB的ZIP。discover_only=true 仅发现分区,不产生可执行计划;新版设计包或知识库包必须显式 sections,正式preview由服务端计算package_sha256和plan_digest。仅Agent时保留旧宽松解析;选择design时严格校验全外包CHECKSUMS、发布身份、JCS业务摘要和源映射。设计-only不解析Agent业务内容、不计划Agent退役;返回逐分区计划,Agent变更含声明的tags并参与变更判断,变更选项后须重新预览。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ResourceImportInput'}
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [package]
|
||
properties:
|
||
package: {type: string, format: binary}
|
||
options: {type: string, description: JSON 编码的认证归属选项}
|
||
responses:
|
||
'200': {description: discovery返回available_sections和支持状态;正式preview返回sections/package_sha256/plan_digest/section_plans,设计计划在design对象中包含publisher_id/release_id/counts/changes/current_revision/snapshot_digest。知识库计划在knowledge对象中包含publisher_id/release_id/changes(slug/name/action/kb_id/documents/folders/images)。知识库分区严格校验v1清单、文件SHA/size和目录树;每次新上传确认导入均创建独立系统库(同一ZIP也不去重);同一次上传的确认重试复用已有成功回执,仅管理员可见,提交后异步学习。已成功分区标记already_imported,不能以整包去重跳过未导分区。}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'409': {description: 资源身份或现有数据关联冲突}
|
||
/api/admin/v1/resource-imports:
|
||
post:
|
||
summary: 按预览确认所选资源分区
|
||
description: 固定agent→design→knowledge顺序,分区独立提交,允许部分成功;HTTP200仍须检查顶层status和逐分区结果。sections/package_sha256/总plan_digest/section_plan_digests须与正式preview一致,options.confirm_final必须true。成功回执与业务写入同事务,重放不重新激活;失败分区重新preview后重试。同upload可在保留期内补导另一分区,过期后保留历史但清理上传字节。旧Agent-only保持既有事务和请求兼容。Agent条目的tags按名称复用或创建标签并同步关联,空数组清空关联,未声明时保留原标签;已有使用授权不变。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- {$ref: '#/components/schemas/ResourceImportInput'}
|
||
- {required: [options, package_sha256, plan_digest]}
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [package, package_sha256, plan_digest, options]
|
||
properties:
|
||
package: {type: string, format: binary}
|
||
package_sha256: {type: string}
|
||
plan_digest: {type: string}
|
||
options: {type: string}
|
||
sections: {type: string, description: JSON编码的分区数组;跨分区分次处理使用封存upload_id}
|
||
section_plan_digests: {type: string, description: JSON编码的逐分区计划}
|
||
responses:
|
||
'200':
|
||
description: 分区结果,status为succeeded或partial;不要仅凭HTTP200显示全部成功。旧Agent-only仍返回原Preview。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
status: {type: string, enum: [succeeded, partial]}
|
||
warning: {type: string, description: 业务已提交但上传状态同步失败的提示}
|
||
sections:
|
||
type: object
|
||
additionalProperties: {$ref: '#/components/schemas/ResourceSectionResult'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'409': {description: 并发变更冲突,需重新预览;无成功分区时error.references包含分区结果}
|
||
'503': {description: 存储/数据库暂不可用;无成功分区时返回错误,不假报成功}
|
||
get:
|
||
summary: 分页查询资源包导入批次
|
||
parameters:
|
||
- {name: cursor, in: query, schema: {type: string}, description: 上一页返回的 next_cursor}
|
||
- {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 500, default: 20}}
|
||
responses:
|
||
'200': {description: 返回items与next_cursor,支持每页最多500条;新分区批次含section_results,status支持succeeded/partial/failed,设计源release不改写为Agent内部版本。}
|
||
/api/admin/v1/resource-imports/{id}:
|
||
get:
|
||
summary: 读取资源包导入批次详情
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: {type: string, format: uuid}
|
||
responses:
|
||
'200': {description: 批次详情}
|
||
'404': {description: 批次不存在}
|
||
/api/admin/v1/sessions/{id}:
|
||
parameters:
|
||
- {name: id, in: path, required: true, schema: {type: string, format: uuid}}
|
||
get:
|
||
summary: 查询会话统计详情
|
||
description: 已清除会话仅返回固定墓碑摘要,不返回轮次或调用明细。
|
||
responses:
|
||
'200': {description: 会话统计元数据,包含标题及来源}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'410': {description: 会话统计数据已清除}
|
||
delete:
|
||
summary: 清除会话及子会话统计明细
|
||
description: 仅管理员可操作;必须提供匹配的顶层会话完整 ID。清除会话与子会话统计明细,并在同一事务写审计;财务流水和会话墓碑保留。
|
||
parameters:
|
||
- {name: X-Confirm-Session-ID, in: header, required: true, schema: {type: string, format: uuid}}
|
||
responses:
|
||
'204': {description: 统计明细已清除}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'403': {$ref: '#/components/responses/ResourceError403'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
/api/admin/v1/statistics/session-reporting/sessions/{id}:
|
||
parameters:
|
||
- {name: id, in: path, required: true, schema: {type: string, format: uuid}}
|
||
get:
|
||
summary: 查询一期会话轮次和网关调用统计详情
|
||
description: 返回会话统计及客户端上报的轮次正文、标题和标题来源;已清除会话普通统计读取返回 410。
|
||
responses:
|
||
'200': {description: 会话标题及来源、轮次正文与截断标记、轮次标题及来源,以及工具、技能、资源、调用与子会话统计}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'410': {description: 会话统计数据已清除}
|
||
/api/admin/v1/statistics/session-reporting/resources:
|
||
get:
|
||
summary: 按用户查询资源开启、使用、调用和失败指标
|
||
description: |
|
||
每行按用户、资源类别、资源 ID 和版本分别聚合;用户为会话所属用户,姓名和邮箱使用当前账户信息。
|
||
包含符合条件的子会话,时间范围为 [from, until),默认最近 24 小时。
|
||
user 按用户名、邮箱或用户 ID 做不区分大小写的字面子串匹配;可与 user_id、kind 及资源筛选组合。
|
||
kind 按原始类别精确筛选,包含快照、工具、技能事件和网关连接器指标;空值表示全部类别。
|
||
资源 ID 和版本按精确值筛选,包含仅有工具调用、没有资源快照条目的资源。
|
||
resource_name 优先采用未删除的后台资源名称,其次采用筛选范围内该用户、资源及版本的最新非空上报名称,最后回退到原始 ID。
|
||
内置工具始终以原始 ID 作为 resource_name;名称不参与分组、排序或 ID 筛选。
|
||
游标与全部筛选条件绑定,旧的跨用户资源聚合游标不再适用。
|
||
parameters:
|
||
- {name: from, in: query, schema: {type: string, format: date-time}}
|
||
- {name: until, in: query, schema: {type: string, format: date-time}}
|
||
- {name: user, in: query, description: 用户名、邮箱或用户 ID,首尾空白会被移除,最多 200 个 Unicode 字符。, schema: {type: string, maxLength: 200}}
|
||
- {name: user_id, in: query, description: 精确匹配会话所属用户 ID。, schema: {type: string, format: uuid}}
|
||
- {name: kind, in: query, description: 原始资源类别,首尾空白会被移除,最多 128 字节;兼容客户端自定义类别。, schema: {type: string, maxLength: 128}}
|
||
- {name: resource_id, in: query, schema: {type: string}}
|
||
- {name: resource_version, in: query, schema: {type: string}}
|
||
- {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 500, default: 50}}
|
||
- {name: cursor, in: query, schema: {type: string}}
|
||
responses:
|
||
'200':
|
||
description: 用户资源维度指标及 next_cursor
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/StatisticsResourceUsage'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
/api/admin/v1/statistics/session-reporting/clients:
|
||
get:
|
||
summary: 查询客户端平台、版本和结局指标
|
||
parameters:
|
||
- {name: from, in: query, schema: {type: string, format: date-time}}
|
||
- {name: until, in: query, schema: {type: string, format: date-time}}
|
||
- {name: client_type, in: query, description: 会话的客户端类型。, schema: {type: string, enum: [desktop, web, extension, mobile, runtime, unknown]}}
|
||
- {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 500, default: 50}}
|
||
- {name: cursor, in: query, schema: {type: string}}
|
||
responses:
|
||
'200': {description: 客户端维度指标及 next_cursor}
|
||
/api/admin/v1/statistics/session-reporting/clients/overview:
|
||
get:
|
||
summary: 查询客户端类型、平台和客户端版本的会话分布
|
||
description: |
|
||
使用与客户端列表一致的轮次筛选和可见范围,包含符合条件的子会话。
|
||
每个 session_id 只计一次,客户端版本取所有筛选条件匹配后的最后一轮,按 started_at、turn_index 降序确定。
|
||
平台为当前设备属性,不是历史快照。空白或缺失客户端版本归入 null;分类不截断。
|
||
三组分类数量之和均等于 total;同数量分类按值稳定排序,null 排最后。
|
||
默认最近 24 小时,时间区间为 [from, until)。不支持 cursor、limit、page、page_size。
|
||
parameters:
|
||
- {name: from, in: query, description: 窗口起点,包含;默认当前时间前 24 小时。, schema: {type: string, format: date-time}}
|
||
- {name: until, in: query, description: 窗口终点,不包含;默认当前时间。, schema: {type: string, format: date-time}}
|
||
- {name: client_type, in: query, description: 会话的客户端类型。, schema: {type: string, enum: [desktop, web, extension, mobile, runtime, unknown]}}
|
||
- {name: platform, in: query, description: 当前设备平台,按客户端上报原值精确匹配,最多 64 个 UTF-8 字节。, schema: {type: string, maxLength: 64}}
|
||
- {name: outcome, in: query, description: 轮次结束原因;先筛选再确定会话的最后匹配轮次。, schema: {type: string, enum: [complete, interrupted, error, max_turns, output_limit, unknown]}}
|
||
- {name: user_id, in: query, description: 会话所属用户 ID。, schema: {type: string, format: uuid}}
|
||
- {name: group_id, in: query, description: 会话所属分组 ID。, schema: {type: string, format: uuid}}
|
||
- {name: model_id, in: query, description: 匹配轮次使用的模型 ID。, schema: {type: string, format: uuid}}
|
||
- {name: expert_id, in: query, description: 会话的专家 ID。, schema: {type: string, format: uuid}}
|
||
- {name: resource_id, in: query, description: 匹配轮次资源快照中的资源 ID,最多 256 字节。, schema: {type: string, maxLength: 256}}
|
||
- {name: resource_version, in: query, description: 匹配资源的版本,最多 256 字节。, schema: {type: string, maxLength: 256}}
|
||
- {name: include_placeholders, in: query, description: 是否包含已上报且有匹配轮次的占位会话。, schema: {type: boolean, default: false}}
|
||
responses:
|
||
'200':
|
||
description: 全量筛选结果的三个分布;空数据 total 为 0,分类均为空数组。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/StatisticsClientOverview'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'403': {$ref: '#/components/responses/Forbidden'}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
/oauth/connectors/{id}/callback:
|
||
get:
|
||
summary: 处理指定 MCP 的 OAuth 回调
|
||
description: 校验 MCP id 与 state 绑定、有效期及配置版本,单次消费授权事务并在服务端交换和保存 Token。无需浏览器会话或 Agent Token。
|
||
security: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: state
|
||
in: query
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: code
|
||
in: query
|
||
description: 授权成功时返回的授权码。
|
||
schema:
|
||
type: string
|
||
- name: error
|
||
in: query
|
||
description: 授权拒绝或取消时返回的错误码。
|
||
schema:
|
||
type: string
|
||
responses:
|
||
'200':
|
||
description: 凭证已保存,浏览器显示授权成功页面。
|
||
content:
|
||
text/html:
|
||
schema:
|
||
type: string
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
/api/auth/v1/methods:
|
||
get:
|
||
summary: 读取公开登录方式开关
|
||
security: []
|
||
responses:
|
||
"200":
|
||
description: 仅包含登录开关,不包含 SMTP 或 OAuth 密钥
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailLoginMethods"
|
||
"503":
|
||
description: 认证配置不可用
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
/api/auth/v1/capabilities:
|
||
get:
|
||
summary: 读取当前可用功能
|
||
description: 无需登录。返回可用功能的布尔值,响应使用 Cache-Control no-store。
|
||
security: []
|
||
responses:
|
||
"200":
|
||
description: 当前生效的能力
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [allow_cloud_computer, allow_custom_branding]
|
||
properties:
|
||
allow_cloud_computer:
|
||
type: boolean
|
||
description: 是否支持新建云电脑。
|
||
allow_custom_branding:
|
||
type: boolean
|
||
description: 是否允许修改和使用团队名称、产品名称及自定义 Logo。
|
||
/api/auth/v1/branding:
|
||
get:
|
||
summary: 读取公开品牌信息
|
||
description: 返回团队名称、产品名称及展示信息。未启用自定义品牌时使用默认名称和空 Logo。
|
||
security: []
|
||
responses:
|
||
"200":
|
||
description: 公开品牌信息
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- workspace_name
|
||
- product_name
|
||
- logo_url
|
||
- machine_code
|
||
- has_commercial_license
|
||
additionalProperties: false
|
||
properties:
|
||
workspace_name:
|
||
type: string
|
||
description: 团队名称。
|
||
product_name:
|
||
type: string
|
||
description: 工具名称。
|
||
logo_url:
|
||
type: string
|
||
description: 自定义 Logo 的绝对 URL,带版本参数;未设置时为空字符串,页面使用内置默认 Logo。
|
||
machine_code:
|
||
type: string
|
||
description: 与管理员付费授权页面相同的授权机器码;宿主未提供时为空字符串,不是统计实例 ID。
|
||
has_commercial_license:
|
||
type: boolean
|
||
description: 是否已导入通过现有付费授权校验且当前有效的商业授权。缺失、无效、过期或无法确认时为 false。
|
||
/api/auth/v1/branding/logo:
|
||
get:
|
||
summary: 读取公开品牌 Logo
|
||
description: 无需登录,返回当前 Logo,统一为 PNG;支持 ETag 条件请求。未设置或存储不可用时返回 404,页面回退默认图片。
|
||
security: []
|
||
parameters:
|
||
- in: query
|
||
name: v
|
||
schema:
|
||
type: string
|
||
description: branding.logo_url 中的图片版本。
|
||
responses:
|
||
"200":
|
||
description: 当前品牌 Logo
|
||
content:
|
||
image/png:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
"304":
|
||
description: Logo 未变化
|
||
"404":
|
||
description: 没有可用的自定义 Logo
|
||
/api/auth/v1/email/code:
|
||
post:
|
||
summary: 发送邮箱验证码
|
||
description: login 受 email_code_enabled 控制;reset 受 password_enabled 控制。每邮箱每分钟最多 1 次、每小时最多 10 次,每连接来源 IP 每小时最多 30
|
||
次;失败发送也计入限额。开启 email_code_auto_registration_enabled 时,新邮箱可获取 login 验证码;
|
||
未开启自动注册的未知邮箱、停用或不符合用途的账号返回相同成功响应但不发送邮件。
|
||
security: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- email
|
||
- purpose
|
||
properties:
|
||
email: &a1
|
||
type: string
|
||
format: email
|
||
maxLength: 254
|
||
description: 邮箱会去除首尾空白并转为小写。
|
||
purpose:
|
||
type: string
|
||
enum:
|
||
- login
|
||
- reset
|
||
responses:
|
||
"200":
|
||
description: 操作成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- message
|
||
- retry_after
|
||
properties:
|
||
message:
|
||
type: string
|
||
retry_after:
|
||
type: integer
|
||
const: 30
|
||
"400":
|
||
description: 请求无效,或验证码无效、过期、超过错误次数限制
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"401":
|
||
description: 邮箱密码不匹配或账号不符合登录入口角色
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"403":
|
||
description: 对应登录方式或注册开关关闭
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"409":
|
||
description: 邮箱已存在,注册冲突
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"429":
|
||
description: 验证码发送过于频繁
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
headers:
|
||
Retry-After:
|
||
schema:
|
||
type: integer
|
||
const: 60
|
||
"500":
|
||
description: 认证操作失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"502":
|
||
description: 邮件发送失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"503":
|
||
description: 认证配置或邮件服务不可用
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
/api/auth/v1/email/reset-password:
|
||
post:
|
||
summary: 通过邮箱验证码重置密码
|
||
description: 使用 reset 用途验证码,需要开启密码登录。重置后撤销全部旧浏览器会话、OAuth token
|
||
和未使用授权码,并使现有登录验证码失效。不会自动登录。
|
||
security: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- email
|
||
- code
|
||
- password
|
||
properties:
|
||
email: *a1
|
||
code: &a2
|
||
type: string
|
||
pattern: ^[0-9]{6}$
|
||
description: 十分钟内有效的六位数字验证码,仅可使用一次。
|
||
password:
|
||
type: string
|
||
minLength: 12
|
||
maxLength: 1024
|
||
writeOnly: true
|
||
description: 新密码至少 12 个字符,长度按 UTF-8 字节校验。
|
||
responses:
|
||
"200":
|
||
description: 操作成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- reset
|
||
properties:
|
||
reset:
|
||
type: boolean
|
||
const: true
|
||
"400":
|
||
description: 请求无效,或验证码无效、过期、超过错误次数限制
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"401":
|
||
description: 邮箱密码不匹配或账号不符合登录入口角色
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"403":
|
||
description: 对应登录方式或注册开关关闭
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"409":
|
||
description: 邮箱已存在,注册冲突
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"429":
|
||
description: 验证码发送过于频繁
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
headers:
|
||
Retry-After:
|
||
schema:
|
||
type: integer
|
||
const: 60
|
||
"500":
|
||
description: 认证操作失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"502":
|
||
description: 邮件发送失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"503":
|
||
description: 认证配置或邮件服务不可用
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
/api/auth/v1/admin/login:
|
||
post:
|
||
summary: 使用密码登录管理后台
|
||
description: 需要开启 password_enabled,仅允许启用状态的管理员;成功设置 HttpOnly、SameSite=Lax 会话
|
||
Cookie,HTTPS 环境附加 Secure。
|
||
security: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- email
|
||
- password
|
||
properties:
|
||
email: *a1
|
||
password:
|
||
type: string
|
||
maxLength: 1024
|
||
writeOnly: true
|
||
responses:
|
||
"200":
|
||
description: 操作成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthUser"
|
||
headers:
|
||
Set-Cookie:
|
||
schema:
|
||
type: string
|
||
description: monkeyai_session 会话 Cookie,默认有效期 7 天。
|
||
"400":
|
||
description: 请求无效,或验证码无效、过期、超过错误次数限制
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"401":
|
||
description: 邮箱密码不匹配或账号不符合登录入口角色
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"403":
|
||
description: 对应登录方式或注册开关关闭
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"409":
|
||
description: 邮箱已存在,注册冲突
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"429":
|
||
description: 验证码发送过于频繁
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
headers:
|
||
Retry-After:
|
||
schema:
|
||
type: integer
|
||
const: 60
|
||
"500":
|
||
description: 认证操作失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"502":
|
||
description: 邮件发送失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"503":
|
||
description: 认证配置或邮件服务不可用
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
/api/auth/v1/admin/email/login:
|
||
post:
|
||
summary: 使用邮箱验证码登录管理后台
|
||
description: 需要开启 email_code_enabled,使用 login
|
||
用途验证码。仅允许启用状态的管理员,成功建立浏览器会话;验证码最多允许 5 次错误尝试。
|
||
此入口不自动创建账号,email_code_auto_registration_enabled 开启也不例外。
|
||
security: []
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- email
|
||
- code
|
||
properties:
|
||
email: *a1
|
||
code: *a2
|
||
responses:
|
||
"200":
|
||
description: 操作成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthUser"
|
||
headers:
|
||
Set-Cookie:
|
||
schema:
|
||
type: string
|
||
description: monkeyai_session 会话 Cookie,默认有效期 7 天。
|
||
"400":
|
||
description: 请求无效,或验证码无效、过期、超过错误次数限制
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"401":
|
||
description: 邮箱密码不匹配或账号不符合登录入口角色
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"403":
|
||
description: 对应登录方式或注册开关关闭
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"409":
|
||
description: 邮箱已存在,注册冲突
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"429":
|
||
description: 验证码发送过于频繁
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
headers:
|
||
Retry-After:
|
||
schema:
|
||
type: integer
|
||
const: 60
|
||
"500":
|
||
description: 认证操作失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"502":
|
||
description: 邮件发送失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"503":
|
||
description: 认证配置或邮件服务不可用
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
/api/admin/v1/settings:
|
||
get:
|
||
summary: 读取管理员设置
|
||
description: branding 记录的 value 包含 logo_url;所有响应隐藏 logo_s3_key。
|
||
responses:
|
||
"200":
|
||
description: 设置列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
settings:
|
||
type: array
|
||
items:
|
||
type: object
|
||
"401":
|
||
description: 未登录
|
||
"403":
|
||
description: 非管理员
|
||
/api/admin/v1/settings/branding:
|
||
get:
|
||
summary: 读取品牌设置
|
||
responses:
|
||
"200":
|
||
description: 品牌设置
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/BrandingSettingRecord"
|
||
"404":
|
||
description: 尚未保存品牌设置
|
||
put:
|
||
summary: 更新品牌名称
|
||
description: JSON 请求只更新名称并保留当前 Logo。multipart 请求在管理员点击保存后原子更新名称和 Logo;logo_action 为 replace 时上传文件,为 reset 时恢复默认。忽略客户端传入的 logo_url 和 logo_s3_key。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [value, schema_version]
|
||
properties:
|
||
schema_version:
|
||
type: integer
|
||
minimum: 1
|
||
value:
|
||
type: object
|
||
required: [workspace_name, product_name]
|
||
properties:
|
||
workspace_name:
|
||
type: string
|
||
minLength: 1
|
||
product_name:
|
||
type: string
|
||
minLength: 1
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [workspace_name, product_name, logo_action]
|
||
properties:
|
||
workspace_name:
|
||
type: string
|
||
minLength: 1
|
||
product_name:
|
||
type: string
|
||
minLength: 1
|
||
logo_action:
|
||
type: string
|
||
enum: [replace, reset]
|
||
logo:
|
||
type: string
|
||
format: binary
|
||
description: replace 时必需;支持 PNG、JPG/JPEG、WebP、GIF、BMP、TIFF,最大 1 MiB,不限制像素尺寸。
|
||
responses:
|
||
"200":
|
||
description: 已保存,包含当前 logo_url
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/BrandingSettingRecord"
|
||
"400":
|
||
description: 品牌名称或请求无效
|
||
/api/admin/v1/settings/branding/logo:
|
||
put:
|
||
summary: 上传或替换品牌 Logo
|
||
description: 管理员上传 PNG、JPG/JPEG、WebP、GIF、BMP 或 TIFF,文件最大 1 MiB,不限制像素尺寸;服务端转成 PNG,GIF/TIFF 使用首帧。成功后立即生效并保留当前品牌名称。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [logo]
|
||
properties:
|
||
logo:
|
||
type: string
|
||
format: binary
|
||
responses:
|
||
"200":
|
||
description: 已保存,logo_url 包含新的版本
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/BrandingSettingRecord"
|
||
"400":
|
||
description: 文件无效或超过限制
|
||
"401":
|
||
description: 未登录
|
||
"403":
|
||
description: 非管理员
|
||
"500":
|
||
description: 保存失败,保留原配置
|
||
"503":
|
||
description: 图片存储不可用
|
||
delete:
|
||
summary: 恢复默认品牌 Logo
|
||
description: 清除自定义 Logo 引用,保留品牌名称。客户端收到空 logo_url 后使用默认图片。
|
||
responses:
|
||
"200":
|
||
description: 已恢复默认
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/BrandingSettingRecord"
|
||
"401":
|
||
description: 未登录
|
||
"403":
|
||
description: 非管理员
|
||
"500":
|
||
description: 保存失败
|
||
/api/admin/v1/settings/mcp:
|
||
get:
|
||
summary: 读取 MCP 网络访问设置
|
||
description: 仅管理员可用。未配置时返回 404,运行时使用空黑名单;默认允许公网和私网。
|
||
responses:
|
||
"200":
|
||
description: MCP 网络访问设置
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/MCPNetworkSetting"
|
||
"404":
|
||
description: 尚未配置黑名单
|
||
put:
|
||
summary: 保存 MCP IP 段黑名单
|
||
description: 完整替换 blocked_cidrs,空数组表示清空黑名单。仅接受 IPv4/IPv6 CIDR,单个地址使用 /32 或 /128。黑名单优先于默认放行及 MONKEYAI_MCP_ALLOWED_CIDRS;保存后对新的 MCP 请求、OAuth 发现、注册及令牌交换生效,包括直连和代理请求,无需重启。配置读取失败时拒绝访问。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [schema_version, value]
|
||
properties:
|
||
schema_version: {type: integer, minimum: 1}
|
||
value:
|
||
$ref: "#/components/schemas/MCPNetworkValue"
|
||
responses:
|
||
"200":
|
||
description: 保存成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/MCPNetworkSetting"
|
||
"400":
|
||
description: 配置格式或 CIDR 无效,原有配置不变
|
||
/api/admin/v1/settings/proxies:
|
||
get:
|
||
summary: 读取系统代理资源
|
||
description: 管理员读取代理列表;密码不返回。未配置时返回 404。
|
||
responses:
|
||
"200":
|
||
description: 系统代理设置
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ProxySetting"
|
||
put:
|
||
summary: 保存系统代理资源
|
||
description: 完整替换代理列表。代理 ID 省略时自动生成;编辑时密码省略或留空则保持旧密码;正在被模型或连接器引用的代理不可删除。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [schema_version, value]
|
||
properties:
|
||
schema_version: {type: integer, minimum: 1}
|
||
value:
|
||
type: object
|
||
required: [proxies]
|
||
properties:
|
||
proxies:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/SystemProxy"
|
||
responses:
|
||
"200":
|
||
description: 保存成功,密码已脱敏
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ProxySetting"
|
||
/api/admin/v1/settings/email/test:
|
||
post:
|
||
summary: 使用已保存 SMTP 配置发送测试邮件
|
||
description: 仅管理员可调用。使用已保存的完整配置(包括未返回前端的密码);SMTP 确认 DATA 后返回成功,连接、TLS、认证或投递失败返回 502。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- recipient
|
||
properties:
|
||
recipient: *a1
|
||
responses:
|
||
"200":
|
||
description: 操作成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- sent
|
||
properties:
|
||
sent:
|
||
type: boolean
|
||
const: true
|
||
"400":
|
||
description: 请求无效,或验证码无效、过期、超过错误次数限制
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"401":
|
||
description: 邮箱密码不匹配或账号不符合登录入口角色
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"403":
|
||
description: 对应登录方式或注册开关关闭
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"409":
|
||
description: 邮箱已存在,注册冲突
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"429":
|
||
description: 验证码发送过于频繁
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
headers:
|
||
Retry-After:
|
||
schema:
|
||
type: integer
|
||
const: 60
|
||
"500":
|
||
description: 认证操作失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"502":
|
||
description: 邮件发送失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
"503":
|
||
description: 认证配置或邮件服务不可用
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/EmailAuthError"
|
||
/api/admin/v1/audits:
|
||
get:
|
||
summary: 查询操作审计
|
||
description: 仅管理员可访问;按发生时间、ID 倒序稳定分页。支持历史记录与请求审计,时间范围左闭右开,文本筛选为不区分大小写的字面子串(IP 除外)。不提供修改或删除接口。
|
||
parameters:
|
||
- name: page
|
||
in: query
|
||
description: 页码,从 1 开始。
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 1000000
|
||
default: 1
|
||
- name: page_size
|
||
in: query
|
||
description: 每页条数。
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 500
|
||
default: 20
|
||
- name: actor
|
||
in: query
|
||
description: 兼容旧链接,按审计记录保存的操作者名称或邮箱做字面子串匹配;新界面先选择用户,再使用 actor_user_id。
|
||
schema:
|
||
type: string
|
||
maxLength: 512
|
||
- name: actor_user_id
|
||
in: query
|
||
description: 操作者用户 UUID 精确匹配,与其他筛选条件取交集。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: ip
|
||
in: query
|
||
description: 实际连接来源 IP 的字面子串,不信任客户端转发头。
|
||
schema:
|
||
type: string
|
||
maxLength: 512
|
||
- name: params
|
||
in: query
|
||
description: 脱敏请求参数的字面子串。
|
||
schema:
|
||
type: string
|
||
maxLength: 512
|
||
- name: category
|
||
in: query
|
||
description: 操作分类。
|
||
schema:
|
||
type: string
|
||
enum: [model, identity, security, settings, resource, billing]
|
||
- name: result
|
||
in: query
|
||
description: 执行结果。
|
||
schema:
|
||
type: string
|
||
enum: [success, failed]
|
||
- name: since
|
||
in: query
|
||
description: 开始时间,包含该时刻。
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: until
|
||
in: query
|
||
description: 结束时间,不包含该时刻,必须晚于开始时间。
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
responses:
|
||
"200":
|
||
description: 匹配的审计记录与总条数;空页的 items 为 [],total 仍为匹配总数。
|
||
headers:
|
||
Cache-Control:
|
||
schema:
|
||
type: string
|
||
const: private, no-store
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/AuditPage"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/ResourceError401"
|
||
"403":
|
||
$ref: "#/components/responses/ResourceError403"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/statistics/models/overview:
|
||
get:
|
||
summary: 模型运行统计、24 小时消息模型分布与近 90 天趋势
|
||
description: |
|
||
仅管理员可访问,不接收查询参数。调用及 Token 按完成时间统计,积分按账本发生时间统计;每日为北京时间(Asia/Shanghai)自然日,今天仅统计到 generated_at。Token 和 TPM 仅累计用量明确的调用:优先采用 billing_transactions.usage.known,缺失时以 model_calls.error_code 为空判断;输入包含缓存输入。调用次数、成功率和耗时仍统计全部已完成调用。首字耗时只使用新采集到首个实际输出片段的流式调用,历史与非流式调用无值。
|
||
message_distribution 与其他字段来自同一只读快照及 generated_at。分布按消息 started_at 统计滚动 24 小时,与会话分析一致:仅统计已上报、非占位、未删除、未清理且已开始的根会话消息,不包含子会话;包含所有消息结果。按模型 UUID 汇总,保留停用或软删除模型的历史名称,缺失模型归入未知项。只返回模型 ID、名称和消息数,不返回配置、密钥、用户资料或消息正文。
|
||
responses:
|
||
"200":
|
||
description: 同一数据库快照下的模型总览。
|
||
headers:
|
||
Cache-Control:
|
||
schema:
|
||
type: string
|
||
const: private, no-store
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/StatisticsModelsOverview"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/ResourceError401"
|
||
"403":
|
||
$ref: "#/components/responses/ResourceError403"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/statistics/realtime:
|
||
get:
|
||
summary: 实时运行统计
|
||
description: 仅管理员可访问。单次请求在同一 PostgreSQL 只读快照中聚合,不返回模拟数据。
|
||
parameters:
|
||
- name: range
|
||
in: query
|
||
required: false
|
||
description: 以服务端当前时间为终点的滚动窗口;5m、30m、60m 仅为旧版调用保留。
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- 5m
|
||
- 15m
|
||
- 30m
|
||
- 60m
|
||
- 1h
|
||
- 4h
|
||
- 1d
|
||
- 7d
|
||
default: 1d
|
||
responses:
|
||
"200":
|
||
description: 统计结果。
|
||
headers:
|
||
Cache-Control:
|
||
schema:
|
||
type: string
|
||
const: private, no-store
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/StatisticsRealtime"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/ResourceError401"
|
||
"403":
|
||
$ref: "#/components/responses/ResourceError403"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/statistics/session-reporting/sessions/overview:
|
||
get:
|
||
summary: 会话分析页面的数量、趋势、模型使用、消息结果与分布统计
|
||
description: |
|
||
仅管理员可访问,不接收查询参数。全部统计来自同一只读快照及同一 generated_at。
|
||
沿用会话历史和消息历史口径:仅统计已启用上报、非占位、未删除、未清理且 started_at 早于 generated_at 的根会话;不包含子会话。保留停用或已删除用户的历史会话,与历史列表一致。消息为 session_turns 中的一条已上报轮次,不是模型调用或输入、输出分别计数。
|
||
会话总量和消息总数覆盖全部历史,未来消息不计入。新增会话按 sessions.started_at,活跃会话按消息 started_at 去重。24 小时窗口为 [generated_at - 24 小时, generated_at),消息数、结果、耗时、每会话消息数及模型使用均使用此窗口。耗时为 ended_at - started_at,包含所有结果;每会话消息数只统计窗口内有消息的会话,跨模型消息合并到所属根会话。P10/P90 使用最近秩法,即排序后取 ceil(N * p) 项;无样本时平均值和百分位返回 null。
|
||
days 为近 90 个北京时间(Asia/Shanghai)自然日,含当天部分数据,升序补零。models 按消息数降序、模型 UUID 升序,未知模型排在同数量已知模型之后;包含已停用、已删除模型的历史用量,model_id 缺失时归入 id/name 为 null 的未知模型。仅返回模型 ID、名称与数量,不返回配置、密钥、消息正文或用户资料。
|
||
responses:
|
||
"200":
|
||
description: 会话分析页面完整数据。
|
||
headers:
|
||
Cache-Control:
|
||
schema: {type: string, const: "private, no-store"}
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/StatisticsSessionOverview"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/ResourceError401"
|
||
"403":
|
||
$ref: "#/components/responses/ResourceError403"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/statistics/session-reporting/members/overview:
|
||
get:
|
||
summary: 成员总数、7 天和 24 小时活跃成员及近 90 天趋势
|
||
description: 仅管理员可访问。固定窗口,不接收查询参数。全部统计只包含当前未软删除的成员,包含管理员和停用成员。活跃指时间范围内存在 session_turns 记录的去重任务所属成员,轮次完成上报后才可统计,与总览活跃口径一致。滚动窗口为左闭右开,7 天严格按 168 小时计算,上一周期为紧邻的同长度窗口。每日趋势按北京时间(Asia/Shanghai)自然日,包含当天部分数据;全部数据来自同一只读快照和同一 generated_at。
|
||
responses:
|
||
"200":
|
||
description: 同时提供三张数字卡片和新增、活跃两张趋势图所需数据。
|
||
headers:
|
||
Cache-Control:
|
||
schema:
|
||
type: string
|
||
const: private, no-store
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/StatisticsMembersOverview"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/ResourceError401"
|
||
"403":
|
||
$ref: "#/components/responses/ResourceError403"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/statistics/session-reporting/members/{id}:
|
||
get:
|
||
summary: 按用户 ID 查询成员使用情况分析
|
||
description: |
|
||
仅管理员可访问;不接收查询参数。不存在或已软删除的成员返回 404,停用成员仍可查询。
|
||
使用同一只读数据库快照和 generated_at 返回成员基本信息、当前分组、近 30 个北京时间自然日(含当天)的任务数、对话数、积分净消耗、本人创建的资源数量、近一年每日对话次数及最近 10 条任务。
|
||
任务和对话沿用任务历史、对话历史口径:只统计已上报、非占位、未删除且未清理的根会话;对话按轮次开始时间,包含空正文及失败轮次,不包含子会话。近 30 天任务数按创建时间统计。积分取同一时间范围用户所有类别的 charge/refund 净额(扣费减退款),以十进制字符串返回,不计额度发放或手动调整,可为负数。
|
||
创建资源统计全部历史未删除资源,包含停用资源及系统/个人资源,不统计授权资源,资源包导入不视为本人创作。专家按 created_by_user_id,其余资源按作为作者持久化的 owner_user_id;大模型包含文本、图片、视频类型。知识库尚无服务端存储,knowledge_bases 固定返回 null。
|
||
activity 从一年前的次日到今天(含首尾,365 或 366 天),按北京时间补零并升序排列;当天仅统计至 generated_at。最近任务按创建时间、ID 倒序,最多 10 条;未核验的对话数量为 null。
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: {type: string, format: uuid}
|
||
responses:
|
||
"200":
|
||
description: 成员分析面板完整数据。
|
||
headers:
|
||
Cache-Control:
|
||
schema: {type: string, const: "private, no-store"}
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/StatisticsMemberAnalysis"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/ResourceError401"
|
||
"403":
|
||
$ref: "#/components/responses/ResourceError403"
|
||
"404":
|
||
$ref: "#/components/responses/ResourceError404"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/statistics/conversations:
|
||
get:
|
||
summary: 分页查询对话轮次历史
|
||
description: 仅管理员可访问。查询已启用上报、非占位、未删除且未清理的根会话轮次,包含空正文;不包含子会话。日期筛选按轮次开始时间,而非任务开始时间,未传日期不限制历史范围。每页多查一条生成 has_next,不执行 COUNT,不返回总数。
|
||
parameters:
|
||
- name: task
|
||
in: query
|
||
description: 按当前任务标题包含匹配,忽略大小写;百分号和下划线作为普通字符。
|
||
schema: {type: string, maxLength: 200}
|
||
- name: task_id
|
||
in: query
|
||
description: 精确匹配根会话 UUID,用于从任务历史进入对话历史。
|
||
schema: {type: string, format: uuid}
|
||
- name: user
|
||
in: query
|
||
description: 兼容旧链接,按用户当前姓名或邮箱包含匹配,忽略大小写;新界面先选择用户,再使用 user_id。
|
||
schema: {type: string, maxLength: 200}
|
||
- name: user_id
|
||
in: query
|
||
description: 按任务所属用户 UUID 精确匹配,同时适用于全局和指定任务的轮次列表,与其他筛选条件取交集。
|
||
schema: {type: string, format: uuid}
|
||
- name: content
|
||
in: query
|
||
description: 按已上报的对话正文包含匹配,忽略大小写;百分号和下划线作为普通字符。
|
||
schema: {type: string, maxLength: 200}
|
||
- name: from
|
||
in: query
|
||
description: 轮次开始时间下界,包含;须携带时区。
|
||
schema: {type: string, format: date-time}
|
||
- name: until
|
||
in: query
|
||
description: 轮次开始时间上界,不包含;须携带时区且晚于 from。日期筛选应传结束日期次日的本地零点。
|
||
schema: {type: string, format: date-time}
|
||
- name: page
|
||
in: query
|
||
description: 页码;超过最后一页时回退到最后一页。
|
||
schema: {type: integer, minimum: 1, maximum: 1000000, default: 1}
|
||
- name: page_size
|
||
in: query
|
||
description: 每页条数。
|
||
schema: {type: integer, minimum: 1, maximum: 500, default: 20}
|
||
responses:
|
||
"200":
|
||
description: 按轮次开始时间、会话 ID、轮次编号降序排列的真实对话记录。
|
||
headers:
|
||
Cache-Control:
|
||
schema: {type: string, const: 'private, no-store'}
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/StatisticsConversations"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/ResourceError401"
|
||
"403":
|
||
$ref: "#/components/responses/ResourceError403"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/statistics/history:
|
||
get:
|
||
summary: 分页查询任务历史
|
||
description: 仅管理员可访问。每页多查一条生成 has_next,不执行总数或逐任务轮次 COUNT。对话数读取 sessions 的已校准缓存,存量后台校准期间为 null。
|
||
parameters:
|
||
- name: task
|
||
in: query
|
||
required: false
|
||
description: 按会话标题或 UUID 包含匹配;百分号和下划线作为普通字符。
|
||
schema:
|
||
type: string
|
||
maxLength: 200
|
||
- name: user
|
||
in: query
|
||
required: false
|
||
description: 兼容旧链接,按用户名或邮箱包含匹配,忽略大小写;新界面先选择用户,再使用 user_id。
|
||
schema:
|
||
type: string
|
||
maxLength: 200
|
||
- name: user_id
|
||
in: query
|
||
required: false
|
||
description: 按任务所属用户 UUID 精确匹配,与用户名/邮箱、任务及日期条件取交集。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: from
|
||
in: query
|
||
required: false
|
||
description: 会话开始时间下界,包含;必须携带时区。
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: until
|
||
in: query
|
||
required: false
|
||
description: 会话开始时间上界,不包含;必须晚于 from。日期筛选应传次日零点。
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- name: page
|
||
in: query
|
||
required: false
|
||
description: 页码。
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 1000000
|
||
default: 1
|
||
- name: page_size
|
||
in: query
|
||
required: false
|
||
description: 每页条数。
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 500
|
||
default: 20
|
||
responses:
|
||
"200":
|
||
description: 统计结果。
|
||
headers:
|
||
Cache-Control:
|
||
schema:
|
||
type: string
|
||
const: private, no-store
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/StatisticsHistory"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/ResourceError401"
|
||
"403":
|
||
$ref: "#/components/responses/ResourceError403"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/billing/settings:
|
||
get:
|
||
summary: 读取计费策略与远程连接状态(不返回证书或私钥)
|
||
description: policy.environment 为可选字段,仅在支持环境定价时返回。
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
policy:
|
||
$ref: '#/components/schemas/BillingPolicy'
|
||
wallet:
|
||
$ref: '#/components/schemas/BillingWalletInfo'
|
||
timezone:
|
||
const: Asia/Shanghai
|
||
next_refresh_at:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
description: 参数不合法
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'401':
|
||
description: 未登录
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'403':
|
||
description: 权限不足
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
/api/admin/v1/billing/settings/{section}:
|
||
parameters:
|
||
- in: path
|
||
name: section
|
||
schema:
|
||
enum:
|
||
- pricing
|
||
- cycle
|
||
- mode
|
||
- wallet
|
||
- environment
|
||
required: true
|
||
patch:
|
||
summary: 独立保存计价、周期、模式、云电脑全局计费或百智云连接配置
|
||
description: environment 节未装配时返回 404,未授权时禁止修改。wallet 配置保存后无需重启,各实例在下次使用时读取。证书和私钥省略或留空时保留原值。首次保存必须提供全部证书。客户端证书与私钥须匹配且处于有效期,私钥须为 PKCS#8 ECDSA 格式。CA 须为有效的 CA 证书。服务 URL 或应用 ID 变更不能影响未完成的远程交易。校验仅在本地执行,不代表远程网络或账户权限验证成功。
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
policy:
|
||
$ref: '#/components/schemas/BillingPolicy'
|
||
wallet:
|
||
$ref: '#/components/schemas/BillingWalletInfo'
|
||
timezone:
|
||
const: Asia/Shanghai
|
||
next_refresh_at:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
description: 参数不合法
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'401':
|
||
description: 未登录
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'403':
|
||
description: 权限不足
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'409':
|
||
description: 修订号冲突,或未完成远程交易阻止服务 URL 或应用 ID 变更
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'422':
|
||
description: 启用远程模式前须先配置有效证书
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
oneOf:
|
||
- type: object
|
||
properties:
|
||
revision:
|
||
type: integer
|
||
input_credits_per_million_tokens:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
cached_input_credits_per_million_tokens:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
output_credits_per_million_tokens:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
required:
|
||
- revision
|
||
- input_credits_per_million_tokens
|
||
- cached_input_credits_per_million_tokens
|
||
- output_credits_per_million_tokens
|
||
- type: object
|
||
properties:
|
||
revision:
|
||
type: integer
|
||
quota_refresh_cycle:
|
||
enum:
|
||
- daily
|
||
- weekly
|
||
- monthly
|
||
required:
|
||
- revision
|
||
- quota_refresh_cycle
|
||
- type: object
|
||
properties:
|
||
revision:
|
||
type: integer
|
||
charging_mode:
|
||
description: local 为本地扣费;remote 为百智云扣费,仅具有有效百智云登录身份的用户可访问系统资源,用户自建资源仍遵循原授权。
|
||
enum:
|
||
- local
|
||
- remote
|
||
enabled:
|
||
type: boolean
|
||
required:
|
||
- revision
|
||
- charging_mode
|
||
- enabled
|
||
- type: object
|
||
additionalProperties: false
|
||
required: [revision, cpu_credits_per_core_hour, memory_credits_per_gib_hour]
|
||
properties:
|
||
revision: {type: integer}
|
||
cpu_credits_per_core_hour:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
memory_credits_per_gib_hour:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
- $ref: '#/components/schemas/BillingWalletInput'
|
||
/api/admin/v1/billing/quotas:
|
||
get:
|
||
summary: 读取分组、成员额度与继承来源
|
||
description: 成员直接所属分组与成员管理一致;周期额度取各所属分组沿父级解析出的有效额度最大值,直属虚拟根节点的成员继承团队额度。
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
groups:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: 分组 UUID;虚拟根节点为 00000000-0000-0000-0000-000000000000。
|
||
parent_id:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
description: 父分组 UUID;仅虚拟根节点为 null,其子分组的父级为全零 UUID。
|
||
name:
|
||
type: string
|
||
credits:
|
||
anyOf:
|
||
- $ref: '#/components/schemas/CreditAmount'
|
||
- type: 'null'
|
||
allow_inherit:
|
||
type: boolean
|
||
description: 是否允许额度留空以继承父级,根节点为 false。
|
||
users:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
email:
|
||
type: string
|
||
avatar_url:
|
||
type: [string, 'null']
|
||
description: 成员当前头像地址;为空时使用默认头像。
|
||
status:
|
||
type: string
|
||
group_ids:
|
||
type: array
|
||
description: 成员直接所属的有效分组 UUID;未加入其他分组时仅包含虚拟根节点的全零 UUID。
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
effective_credits:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
balance_credits:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
description: 当前周期账户的账面剩余;尚未开户时等于有效周期额度。
|
||
available_credits:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
description: 当前周期账户的可用积分(等于账面剩余);尚未开户时等于有效周期额度。
|
||
inherited_from:
|
||
type: string
|
||
description: 最高有效额度的来源分组 UUID(含虚拟根的全零 UUID)。额度相同时按直接所属分组的创建时间、ID 稳定选取。
|
||
external_user_id:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
revision:
|
||
type: integer
|
||
effective_at:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
put:
|
||
summary: 批量更新分组周期额度,下周期生效
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
groups:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: 分组 UUID;虚拟根节点为 00000000-0000-0000-0000-000000000000。
|
||
parent_id:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
description: 父分组 UUID;仅虚拟根节点为 null,其子分组的父级为全零 UUID。
|
||
name:
|
||
type: string
|
||
credits:
|
||
anyOf:
|
||
- $ref: '#/components/schemas/CreditAmount'
|
||
- type: 'null'
|
||
allow_inherit:
|
||
type: boolean
|
||
description: 是否允许额度留空以继承父级,根节点为 false。
|
||
users:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
email:
|
||
type: string
|
||
avatar_url:
|
||
type: [string, 'null']
|
||
description: 成员当前头像地址;为空时使用默认头像。
|
||
status:
|
||
type: string
|
||
group_ids:
|
||
type: array
|
||
description: 成员直接所属的有效分组 UUID;未加入其他分组时仅包含虚拟根节点的全零 UUID。
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
effective_credits:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
balance_credits:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
description: 当前周期账户的账面剩余;尚未开户时等于有效周期额度。
|
||
available_credits:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
description: 当前周期账户的可用积分(等于账面剩余);尚未开户时等于有效周期额度。
|
||
inherited_from:
|
||
type: string
|
||
description: 最高有效额度的来源分组 UUID(含虚拟根的全零 UUID)。额度相同时按直接所属分组的创建时间、ID 稳定选取。
|
||
external_user_id:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
revision:
|
||
type: integer
|
||
effective_at:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
revision:
|
||
type: integer
|
||
changes:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
subject_type:
|
||
enum:
|
||
- group
|
||
id:
|
||
type: string
|
||
description: 分组 UUID;团队默认额度使用虚拟根的全零 UUID。
|
||
credits:
|
||
description: 非负整数积分;null 表示继承上级额度。
|
||
anyOf:
|
||
- $ref: '#/components/schemas/CreditAmount'
|
||
- type: 'null'
|
||
required:
|
||
- subject_type
|
||
- id
|
||
- credits
|
||
required:
|
||
- revision
|
||
- changes
|
||
/api/admin/v1/billing/quotas/reset:
|
||
post:
|
||
summary: 立即重置所选分组和成员的当前周期额度
|
||
description: 分组包含所有后代分组的成员;成员自动去重。仅直接计费模式可用。重置当前余额和周期额度快照,并记录重置流水与审计。
|
||
responses:
|
||
'200':
|
||
description: 重置成功或幂等重放成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
reset_count:
|
||
type: integer
|
||
required:
|
||
- reset_count
|
||
'400':
|
||
description: 请求格式不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'404':
|
||
description: 分组或成员不存在
|
||
'409':
|
||
description: 非直接计费模式或幂等键冲突
|
||
'422':
|
||
description: 选择为空、数量超限或没有可重置成员
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
group_ids:
|
||
type: array
|
||
maxItems: 1000
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
user_ids:
|
||
type: array
|
||
maxItems: 1000
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
idempotency_key:
|
||
type: string
|
||
format: uuid
|
||
required:
|
||
- group_ids
|
||
- user_ids
|
||
- idempotency_key
|
||
/api/admin/v1/billing/accounts/{userID}:
|
||
parameters:
|
||
- in: path
|
||
name: userID
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
required: true
|
||
get:
|
||
summary: 查询当期积分账户
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
account:
|
||
$ref: '#/components/schemas/CreditAccount'
|
||
user_name:
|
||
type: string
|
||
description: 积分账户所属用户的当前姓名。
|
||
user_email:
|
||
type: string
|
||
format: email
|
||
description: 积分账户所属用户的当前邮箱。
|
||
external_user_id:
|
||
type: string
|
||
wallet:
|
||
$ref: '#/components/schemas/BillingWalletInfo'
|
||
wallet_available:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
wallet_queried_at:
|
||
type: string
|
||
format: date-time
|
||
wallet_error:
|
||
type: string
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
/api/admin/v1/billing/accounts/{userID}/adjustments:
|
||
parameters:
|
||
- in: path
|
||
name: userID
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
required: true
|
||
post:
|
||
summary: 幂等调整当期积分
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
oneOf:
|
||
- type: object
|
||
properties:
|
||
account:
|
||
$ref: '#/components/schemas/CreditAccount'
|
||
external_user_id:
|
||
type: string
|
||
wallet:
|
||
$ref: '#/components/schemas/BillingWalletInfo'
|
||
wallet_available:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
wallet_queried_at:
|
||
type: string
|
||
format: date-time
|
||
wallet_error:
|
||
type: string
|
||
- $ref: '#/components/schemas/CreditAccount'
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 该账户版本已提交过不同的调整
|
||
'412':
|
||
description: 账户版本已过期,请刷新后重试
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
delta:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
reason:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 500
|
||
version:
|
||
type: string
|
||
description: 读取当前账户时返回的版本。相同版本与内容重试不会重复调整;账户变化后须刷新版本。
|
||
maxLength: 128
|
||
required:
|
||
- delta
|
||
- reason
|
||
- version
|
||
/api/admin/v1/billing/accounts/{userID}/wallet:
|
||
parameters:
|
||
- in: path
|
||
name: userID
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
required: true
|
||
put:
|
||
summary: 核实并绑定百智云身份,有未完成远程交易时拒绝修改
|
||
description: external_user_id 必须匹配该用户有效百智云登录身份的 sub;普通 OAuth/OIDC 身份和历史手动绑定不能代替百智云身份。未指定绑定且只有一个百智云身份时自动使用其 sub。
|
||
responses:
|
||
'204':
|
||
description: 绑定成功
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
external_user_id:
|
||
type: string
|
||
required:
|
||
- external_user_id
|
||
/api/admin/v1/billing/users:
|
||
get:
|
||
summary: 按需搜索扣费筛选的用户候选
|
||
description: 搜索当前用户姓名、邮箱或 ID,包含停用和已删除用户,以便查询其历史流水。返回有界候选而非全量成员;选中后向 entries 或 summary 传 user_id。未选中时仍可通过 user 搜索历史姓名和邮箱。
|
||
parameters:
|
||
- in: query
|
||
name: q
|
||
description: 不区分大小写的字面子串,去除首尾空格后最多 200 个字符。
|
||
schema:
|
||
type: string
|
||
maxLength: 200
|
||
- in: query
|
||
name: id
|
||
description: 用于恢复 URL 中已选用户的显示信息;可与 q 同时提供,取交集。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- in: query
|
||
name: limit
|
||
schema:
|
||
type: integer
|
||
default: 20
|
||
minimum: 1
|
||
maximum: 50
|
||
responses:
|
||
'200':
|
||
description: 返回姓名、邮箱、头像和删除标记,不返回账户、角色或登录等信息。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [items, has_next]
|
||
properties:
|
||
has_next:
|
||
type: boolean
|
||
items:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required: [id, name, email, avatar_url, deleted]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
email:
|
||
type: string
|
||
avatar_url:
|
||
type: [string, 'null']
|
||
deleted:
|
||
type: boolean
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
/api/admin/v1/billing/entries:
|
||
get:
|
||
summary: 分页查询不可变积分流水
|
||
description: 读取不可变账本,不执行 COUNT 或返回精确总数。每页最多查询 page_size 加一条,以 has_next 判断后续页。时间范围为左闭右开;from 和 until 均未传入时,默认北京时间最近 28 个自然日(含今天)。range=all 显式取消默认范围;已提供的单侧或双侧时间条件保持原样。响应 from/until 返回实际生效的边界。
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/CreditEntry'
|
||
has_next:
|
||
type: boolean
|
||
from:
|
||
type: [string, 'null']
|
||
format: date-time
|
||
until:
|
||
type: [string, 'null']
|
||
format: date-time
|
||
page:
|
||
type: integer
|
||
page_size:
|
||
type: integer
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
parameters:
|
||
- in: query
|
||
name: user_id
|
||
description: 按用户 UUID 精确筛选,利用现有用户与时间索引;与其他筛选条件取交集。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- in: query
|
||
name: user
|
||
description: 对流水固化的历史姓名或邮箱做子串搜索;与 user_id 同时提供时取交集。
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: content
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: category
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: mode
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: entry_type
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: group_id
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: from
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- in: query
|
||
name: until
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- in: query
|
||
name: page
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
- in: query
|
||
name: page_size
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 500
|
||
- in: query
|
||
name: range
|
||
description: 仅支持 all,表示显式取消缺省时间范围;仍保留已提供的 from/until。
|
||
schema:
|
||
type: string
|
||
enum: [all]
|
||
/api/admin/v1/billing/summary:
|
||
get:
|
||
summary: 按同一筛选口径汇总扣费和退款
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
charges:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
refunds:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
net_consumption:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
count:
|
||
type: integer
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
parameters:
|
||
- in: query
|
||
name: user_id
|
||
description: 按用户 UUID 精确筛选,利用现有用户与时间索引;与其他筛选条件取交集。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- in: query
|
||
name: user
|
||
description: 对流水固化的历史姓名或邮箱做子串搜索;与 user_id 同时提供时取交集。
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: content
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: category
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: mode
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: entry_type
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: group_id
|
||
schema:
|
||
type: string
|
||
- in: query
|
||
name: from
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- in: query
|
||
name: until
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
/api/admin/v1/billing/reconciliation:
|
||
get:
|
||
summary: 查询未完成交易、本地账目差异和旧配置迁移问题
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/BillingTransaction'
|
||
total:
|
||
type: integer
|
||
page:
|
||
type: integer
|
||
page_size:
|
||
type: integer
|
||
differences:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
account_id:
|
||
type: string
|
||
format: uuid
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
balance:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
ledger_balance:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
frozen:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
description: 遗留冻结额,迁移后通常为零;非零时作为账目异常报告。
|
||
migration_issues:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: integer
|
||
subject:
|
||
type: string
|
||
value: {}
|
||
reason:
|
||
type: string
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
parameters:
|
||
- in: query
|
||
name: page
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
- in: query
|
||
name: page_size
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 500
|
||
/api/admin/v1/billing/transactions/{id}:
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
required: true
|
||
get:
|
||
summary: 读取调用、用量、价格快照、流水及钱包记录
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BillingTransaction'
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
/api/admin/v1/billing/transactions/{id}/retry:
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
required: true
|
||
post:
|
||
summary: 重试已确定用量的待结算交易
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BillingTransaction'
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties: {}
|
||
/api/admin/v1/billing/transactions/{id}/resolve:
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
required: true
|
||
post:
|
||
summary: 按核实证据处理结果未知的交易
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BillingTransaction'
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
usage:
|
||
$ref: '#/components/schemas/BillingUsage'
|
||
reason:
|
||
type: string
|
||
required:
|
||
- usage
|
||
- reason
|
||
/api/admin/v1/billing/transactions/{id}/refund:
|
||
parameters:
|
||
- in: path
|
||
name: id
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
required: true
|
||
post:
|
||
summary: 全额冲正本地已结算扣款,同一交易只退款一次
|
||
responses:
|
||
'200':
|
||
description: 请求成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/BillingTransaction'
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 权限不足
|
||
'409':
|
||
description: 修订号、幂等键或交易状态冲突
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
reason:
|
||
type: string
|
||
required:
|
||
- reason
|
||
/api/admin/v1/users:
|
||
get:
|
||
summary: 查询管理端成员列表
|
||
description: 返回未删除的成员及其直接负责的有效分组,不继承子分组,不改变成员的全局角色。
|
||
responses:
|
||
'200':
|
||
description: 成员列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [users]
|
||
properties:
|
||
users:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/AdminListUser'}
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
post:
|
||
summary: 创建用户并加入分组
|
||
description: 创建用户、保存密码哈希与写入全部直接分组关系在同一事务内完成,任一失败全部回滚。普通成员自动生成包含数字及大小写字母的 16 位随机初始密码,忽略请求中的 password;管理员使用请求中填写的初始密码。密码明文仅在创建成功的本次响应中通过 initial_password 返回,不写入成员资料、缓存或日志。group_ids 未传、为 null 或为空数组时不建立分组关系,用户自动显示在虚拟根分组下。重复分组 ID 自动去重,不可选择根分组、不存在或已删除的分组。只加入指定分组,不自动加入其父分组或子分组。批量添加可逐个调用此接口,每个用户独立提交。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/CreateAdminUserInput'
|
||
responses:
|
||
'201':
|
||
description: 用户、密码与全部分组关系已创建,初始密码仅本次返回。
|
||
headers:
|
||
Cache-Control:
|
||
schema:
|
||
type: string
|
||
const: no-store
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AdminUserCreationResult'
|
||
'400':
|
||
description: invalid_request,请求字段或所选分组无效,未创建用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'409':
|
||
description: user_exists,该邮箱已被未删除用户占用。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
'500':
|
||
description: server_error,创建失败,用户与分组关系全部回滚。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ErrorResponse'
|
||
/api/admin/v1/users/{userID}:
|
||
parameters:
|
||
- in: path
|
||
name: userID
|
||
required: true
|
||
description: 成员 UUID。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
get:
|
||
summary: 根据 ID 查询成员资料
|
||
description: 返回成员资料及其直接负责的有效分组。没有负责的分组时 supervised_groups 为空数组;已删除或不存在的成员返回 404。
|
||
responses:
|
||
'200':
|
||
description: 成员资料及主管分组,与管理端成员列表中的单项一致。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AdminListUser'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
/api/admin/v1/users/{userID}/reset-password:
|
||
parameters:
|
||
- in: path
|
||
name: userID
|
||
required: true
|
||
description: 成员 UUID。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
post:
|
||
summary: 管理员重置成员密码
|
||
description: 生成包含数字及大小写字母的 16 位随机密码,替换指定成员的密码并撤销旧会话、OAuth token、授权码与未使用的登录和重置验证码。被停用的成员仍保持停用。密码明文只在本次响应返回,客户端不得缓存或记录。
|
||
responses:
|
||
"200":
|
||
description: 密码已重置,仅本次响应包含新密码。
|
||
headers:
|
||
Cache-Control:
|
||
schema:
|
||
type: string
|
||
const: no-store
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [password]
|
||
properties:
|
||
password:
|
||
type: string
|
||
minLength: 16
|
||
maxLength: 16
|
||
pattern: "^[A-Za-z0-9]{16}$"
|
||
description: 仅本次返回的随机密码。
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"404":
|
||
$ref: "#/components/responses/ResourceError404"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/groups:
|
||
get:
|
||
summary: 查询成员分组
|
||
description: 返回全零 UUID 的虚拟根分组和全部未删除子分组。根节点不入库,名称来自 branding.workspace_name,直属成员为未直接加入其他有效分组的用户;真实顶层分组的 parent_id 在响应中为根分组 UUID,数据库中仍为 null。actions 和 allow_add_members 由后端决定。
|
||
responses:
|
||
"200":
|
||
description: 分组列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/MemberGroupsResponse"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
post:
|
||
summary: 创建子分组
|
||
description: 名称去除首尾空白后须为 1—100 个字符,同级名称不区分大小写且不能重复。parent_id 为全零 UUID、null 或省略时,创建根节点的直属子分组。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/CreateMemberGroupInput"
|
||
responses:
|
||
"201":
|
||
description: 已创建分组
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/MemberGroup"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"404":
|
||
$ref: "#/components/responses/ResourceError404"
|
||
"409":
|
||
$ref: "#/components/responses/ResourceError409"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/groups/move:
|
||
post:
|
||
summary: 批量移动分组或成员
|
||
description: 管理员确认拖放预览后一次提交,全部变更在同一事务中完成。不能混合移动分组与成员;移动父分组会保留子树,不能同时选择其子分组、移动到自身/后代或在目标下造成同名冲突。树中成员仅移除指定来源分组,保留其他分组关系;未指定来源的列表成员只加入目标分组。全零 UUID 为虚拟根目标,不能直接增加成员关系。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/MemberGroupMoveInput"
|
||
responses:
|
||
"204":
|
||
description: 批量移动成功,无响应体。
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"404":
|
||
$ref: "#/components/responses/ResourceError404"
|
||
"409":
|
||
$ref: "#/components/responses/ResourceError409"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/groups/{groupID}:
|
||
parameters:
|
||
- in: path
|
||
name: groupID
|
||
required: true
|
||
description: 分组 UUID。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
patch:
|
||
summary: 修改分组名称或上级分组
|
||
description: 至少指定 name 或 parent_id。parent_id 为全零 UUID 或 null 表示移动到根节点下,省略则保留原上级。不能移动到自身或后代中;更换上级会改变成员继承的资源授权。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/MemberGroupInput"
|
||
responses:
|
||
"200":
|
||
description: 已更新分组
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/MemberGroup"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"404":
|
||
$ref: "#/components/responses/ResourceError404"
|
||
"409":
|
||
$ref: "#/components/responses/ResourceError409"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
delete:
|
||
summary: 删除分组
|
||
description: 有子分组时返回 409。软删除分组、移除直接成员关系并清除本组资源授权,保留成员账号;额度自动按其余所属分组重新计算,不改变当期账户。
|
||
responses:
|
||
"204":
|
||
description: 已删除,无响应体。
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"404":
|
||
$ref: "#/components/responses/ResourceError404"
|
||
"409":
|
||
$ref: "#/components/responses/ResourceError409"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/groups/{groupID}/members:
|
||
parameters:
|
||
- in: path
|
||
name: groupID
|
||
required: true
|
||
description: 分组 UUID。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
put:
|
||
summary: 替换分组直接成员
|
||
description: 调整直接成员关系,不改变用户角色或子分组成员。空数组清空直接成员,重复 ID 自动去重。成员额度随分组关系继承,多个分组取最高有效额度;变更不重发当期额度。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/MemberGroupMembersInput"
|
||
responses:
|
||
"200":
|
||
description: 已更新成员关系
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/MemberGroup"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"404":
|
||
$ref: "#/components/responses/ResourceError404"
|
||
"409":
|
||
$ref: "#/components/responses/ResourceError409"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/groups/{groupID}/supervisors:
|
||
parameters:
|
||
- in: path
|
||
name: groupID
|
||
required: true
|
||
schema: {type: string, format: uuid}
|
||
put:
|
||
summary: 替换分组主管名单
|
||
description: 仅超级管理员可操作。仅接受该实际分组未删除的直属成员;重复 ID 去重,空数组清空。任一成员归属无效时整次拒绝,不改变成员关系、全局角色或登录权限。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [supervisor_ids]
|
||
properties:
|
||
supervisor_ids:
|
||
type: array
|
||
maxItems: 10000
|
||
items: {type: string, format: uuid}
|
||
responses:
|
||
"200":
|
||
description: 更新后的分组及主管名单
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/MemberGroup"
|
||
"400":
|
||
$ref: "#/components/responses/ResourceError400"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"404":
|
||
$ref: "#/components/responses/ResourceError404"
|
||
"409":
|
||
$ref: "#/components/responses/ResourceError409"
|
||
"500":
|
||
$ref: "#/components/responses/ResourceError500"
|
||
/api/admin/v1/models:
|
||
get:
|
||
summary: 查询模型
|
||
description: |
|
||
按 ownership_type 分别查询系统或用户模型。q 按名称、模型 ID 或上游地址进行不区分大小写的字面子串搜索。
|
||
提供 limit、cursor 或 q 时启用按 ID 稳定排序的游标分页;筛选在分页前执行,切换类型或关键词时应清空 cursor。
|
||
未提供上述三个参数时保留完整列表及创建时间倒序;next_cursor 为空表示无后续页。
|
||
parameters:
|
||
- in: query
|
||
name: q
|
||
description: 按名称、模型 ID 或上游地址搜索;空值不筛选。
|
||
schema: {type: string}
|
||
- in: query
|
||
name: cursor
|
||
description: 上一页返回的 next_cursor。
|
||
schema: {type: string}
|
||
- in: query
|
||
name: limit
|
||
description: 单页数量;提供分页参数时默认 200。
|
||
schema: {type: integer, minimum: 1, maximum: 500, default: 200}
|
||
- in: query
|
||
name: ownership_type
|
||
description: 按模型所有权类型筛选;不传时不过滤所有权类型。
|
||
schema:
|
||
type: string
|
||
enum: [system, user]
|
||
responses:
|
||
"200":
|
||
description: 模型列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ModelsResponse"
|
||
"400":
|
||
$ref: "#/components/responses/BadRequest"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
post:
|
||
summary: 创建系统模型
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/CreateModelInput"
|
||
responses:
|
||
"201":
|
||
description: 创建成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Model"
|
||
"400":
|
||
$ref: "#/components/responses/BadRequest"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
/api/admin/v1/models/discover:
|
||
post:
|
||
summary: 使用上游连接配置查询可用的大语言模型
|
||
description: 服务端 GET Base URL 下的 models 接口,使用对应协议鉴权;不跟随重定向、不返回密钥。支持已保存密钥和网络代理,超时 15 秒,响应不缓存。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [base_url, protocol]
|
||
anyOf:
|
||
- required: [api_key]
|
||
properties:
|
||
api_key: {minLength: 1}
|
||
- required: [model_resource_id]
|
||
properties:
|
||
base_url: {type: string, format: uri}
|
||
protocol: {type: string, enum: [openai_chat_completions, openai_responses, anthropic]}
|
||
api_key: {type: string, writeOnly: true, maxLength: 16384, description: 编辑已有系统文本模型时可留空,以使用其已保存密钥。}
|
||
model_resource_id: {type: string, format: uuid}
|
||
proxy_id: {type: string, description: 网络代理 ID;空字符串表示不使用代理。}
|
||
responses:
|
||
'200':
|
||
description: 按 ID 排序并去重的模型列表;上游分页会被合并,最多 2000 个。
|
||
headers:
|
||
Cache-Control: {schema: {type: string, enum: [no-store]}}
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [models]
|
||
properties:
|
||
models:
|
||
type: array
|
||
maxItems: 2000
|
||
items:
|
||
type: object
|
||
required: [id]
|
||
properties:
|
||
id: {type: string}
|
||
'400': {$ref: '#/components/responses/BadRequest'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'403': {$ref: '#/components/responses/Forbidden'}
|
||
'502':
|
||
description: 上游请求失败或模型列表响应无效。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ErrorResponse'}
|
||
'504':
|
||
description: 上游请求超时。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ErrorResponse'}
|
||
/api/admin/v1/models/{modelID}/probe:
|
||
post:
|
||
summary: 使用已保存配置测试系统大语言模型或向量模型
|
||
description: 按模型协议、Base URL、已保存密钥和网络代理向上游发送非流式请求,不缓存、不跟随重定向。大语言模型使用对应协议接口,返回提取的文本和响应有效性;向量模型将 message 作为 embedding 输入,返回维度、配置一致性、向量预览和 Token 用量。
|
||
parameters:
|
||
- {name: modelID, in: path, required: true, schema: {type: string, format: uuid}}
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [message]
|
||
properties:
|
||
message: {type: string, minLength: 1, maxLength: 4000, description: 大语言模型的测试消息或向量模型的 embedding 输入。}
|
||
responses:
|
||
'200':
|
||
description: 大语言模型或向量模型的 JSON 测试结果。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
oneOf:
|
||
- type: object
|
||
required: [content, valid]
|
||
properties:
|
||
content: {type: string}
|
||
valid: {type: boolean, description: 上游响应是否包含对应协议的合法文本内容。}
|
||
- $ref: '#/components/schemas/EmbeddingProbeResult'
|
||
'400': {$ref: '#/components/responses/BadRequest'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'403': {$ref: '#/components/responses/Forbidden'}
|
||
'404': {$ref: '#/components/responses/NotFound'}
|
||
'502':
|
||
description: 连接模型失败、代理不可用或上游返回错误。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ErrorResponse'}
|
||
'504':
|
||
description: 上游模型响应超时。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ErrorResponse'}
|
||
/api/admin/v1/models/image-capabilities:
|
||
get:
|
||
summary: 查询生图模型支持的画质、比例和操作
|
||
parameters:
|
||
- {name: provider, in: query, required: true, schema: {$ref: '#/components/schemas/ModelProvider'}}
|
||
responses:
|
||
'200':
|
||
description: 供应商代码声明的原始能力,供管理员选择开放画质与比例。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [operations, qualities, aspect_ratios, max_images, max_reference_images, supports_reference_image, supports_mask]
|
||
properties:
|
||
operations: {type: array, items: {type: string, enum: [generate, edit]}}
|
||
qualities: {type: array, items: {$ref: '#/components/schemas/ImageQuality'}}
|
||
aspect_ratios: {type: array, items: {type: string}}
|
||
allowed_aspect_ratios: {type: object}
|
||
max_images: {type: integer, minimum: 1}
|
||
max_reference_images: {type: integer, minimum: 0}
|
||
supports_reference_image: {type: boolean}
|
||
supports_mask: {type: boolean}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/Unauthorized'}
|
||
'403': {$ref: '#/components/responses/Forbidden'}
|
||
/api/admin/v1/models/authorization-subjects:
|
||
get:
|
||
summary: 查询可授权的用户和分组
|
||
responses:
|
||
"200":
|
||
description: 授权对象
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/AuthorizationSubjects"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"500":
|
||
$ref: "#/components/responses/InternalError"
|
||
/api/admin/v1/models/{modelID}:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ModelID"
|
||
put:
|
||
summary: 更新系统模型
|
||
description: api_key 为空时保留原有上游密钥。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ModelInput"
|
||
responses:
|
||
"200":
|
||
description: 更新成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Model"
|
||
"400":
|
||
$ref: "#/components/responses/BadRequest"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"404":
|
||
$ref: "#/components/responses/NotFound"
|
||
delete:
|
||
summary: 删除系统模型
|
||
responses:
|
||
"204":
|
||
description: 删除成功,无响应体。
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"404":
|
||
$ref: "#/components/responses/NotFound"
|
||
"500":
|
||
$ref: "#/components/responses/InternalError"
|
||
/api/admin/v1/models/{modelID}/enabled:
|
||
parameters:
|
||
- $ref: "#/components/parameters/ModelID"
|
||
patch:
|
||
summary: 启用或停用系统模型
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/SetModelEnabledInput"
|
||
responses:
|
||
"200":
|
||
description: 更新成功
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/Model"
|
||
"400":
|
||
$ref: "#/components/responses/BadRequest"
|
||
"401":
|
||
$ref: "#/components/responses/Unauthorized"
|
||
"403":
|
||
$ref: "#/components/responses/Forbidden"
|
||
"404":
|
||
$ref: "#/components/responses/NotFound"
|
||
"500":
|
||
$ref: "#/components/responses/InternalError"
|
||
/api/admin/v1/api-keys:
|
||
get:
|
||
summary: 查询调用密钥
|
||
parameters:
|
||
- in: query
|
||
name: user_id
|
||
description: 按密钥所属用户筛选;不传时返回全部调用密钥。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 调用密钥元数据列表,不包含密钥原文。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/APIKeysResponse'
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'500':
|
||
$ref: '#/components/responses/InternalError'
|
||
/api/admin/v1/api-keys/{keyID}:
|
||
parameters:
|
||
- $ref: '#/components/parameters/KeyID'
|
||
delete:
|
||
summary: 管理员撤销调用密钥
|
||
responses:
|
||
'204':
|
||
description: 撤销成功,无响应体。
|
||
'401':
|
||
$ref: '#/components/responses/Unauthorized'
|
||
'403':
|
||
$ref: '#/components/responses/Forbidden'
|
||
'404':
|
||
$ref: '#/components/responses/NotFound'
|
||
'500':
|
||
$ref: '#/components/responses/InternalError'
|
||
/api/admin/v1/feedback:
|
||
get:
|
||
summary: 分页查询用户反馈
|
||
parameters:
|
||
- name: page
|
||
in: query
|
||
schema: {type: integer, minimum: 1, maximum: 1000000, default: 1}
|
||
- name: page_size
|
||
in: query
|
||
schema: {type: integer, minimum: 1, maximum: 500, default: 20}
|
||
- name: category
|
||
in: query
|
||
schema: {type: string, enum: [bug, feature, experience, other]}
|
||
- name: state
|
||
in: query
|
||
schema: {type: string, enum: [uploading, new, resolved, ignored, failed]}
|
||
responses:
|
||
'200':
|
||
description: 反馈分页
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/FeedbackPage'
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'403': {$ref: '#/components/responses/ResourceError403'}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
/api/admin/v1/feedback/{id}:
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: {type: string, format: uuid}
|
||
get:
|
||
summary: 读取用户反馈详情
|
||
responses:
|
||
'200':
|
||
description: 反馈详情
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Feedback'
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'403': {$ref: '#/components/responses/ResourceError403'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
patch:
|
||
summary: 更新用户反馈状态
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [state]
|
||
properties:
|
||
state:
|
||
type: string
|
||
enum: [uploading, new, resolved, ignored, failed]
|
||
responses:
|
||
'200':
|
||
description: 更新后的反馈
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Feedback'
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'403': {$ref: '#/components/responses/ResourceError403'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
/api/admin/v1/feedback/{id}/attachments/{attachmentID}:
|
||
get:
|
||
summary: 下载用户反馈图片
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: {type: string, format: uuid}
|
||
- name: attachmentID
|
||
in: path
|
||
required: true
|
||
schema: {type: string, format: uuid}
|
||
responses:
|
||
'200':
|
||
description: 反馈图片
|
||
content:
|
||
image/png: {schema: {type: string, format: binary}}
|
||
image/jpeg: {schema: {type: string, format: binary}}
|
||
image/webp: {schema: {type: string, format: binary}}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'403': {$ref: '#/components/responses/ResourceError403'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
/api/admin/v1/rules:
|
||
get:
|
||
summary: 查询Rule
|
||
description: |
|
||
按 ownership_type 筛选系统或用户规则;省略时返回两类规则。
|
||
q 对名称和完整规则内容进行不区分大小写的字面子串搜索;空值不筛选。
|
||
筛选在游标分页前执行;切换类型或搜索关键词时应清空 cursor。
|
||
limit 控制单页数量,后续页使用 next_cursor 请求,不返回已删除的规则。
|
||
responses:
|
||
'200':
|
||
description: 查询Rule
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/RuleResource'
|
||
next_cursor:
|
||
type: string
|
||
required:
|
||
- items
|
||
- next_cursor
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: ownership_type
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- system
|
||
- user
|
||
- name: q
|
||
in: query
|
||
schema:
|
||
type: string
|
||
- name: cursor
|
||
in: query
|
||
schema:
|
||
type: string
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 500
|
||
default: 200
|
||
post:
|
||
summary: 创建Rule
|
||
responses:
|
||
'200':
|
||
description: 创建Rule
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/RuleResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/RuleInput'
|
||
/api/admin/v1/rules/{id}:
|
||
get:
|
||
summary: 读取Rule
|
||
responses:
|
||
'200':
|
||
description: 读取Rule
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/RuleResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
put:
|
||
summary: 更新Rule
|
||
responses:
|
||
'200':
|
||
description: 更新Rule
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/RuleResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/RuleInput'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
delete:
|
||
summary: 删除Rule
|
||
responses:
|
||
'204':
|
||
description: 删除Rule
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/rules/{id}/enabled:
|
||
patch:
|
||
summary: 启停规则
|
||
description: 支持管理员创建和资源包导入的规则。手动启停设置会保留到后续资源包更新。
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: {type: string, format: uuid}
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema: {type: string}
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [enabled]
|
||
properties:
|
||
enabled: {type: boolean}
|
||
responses:
|
||
'200':
|
||
description: 更新后的规则
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/RuleResource'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'403': {$ref: '#/components/responses/ResourceError403'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'409': {$ref: '#/components/responses/ResourceError409'}
|
||
'412': {$ref: '#/components/responses/ResourceError412'}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
/api/admin/v1/skills:
|
||
get:
|
||
summary: 查询Skill
|
||
description: |
|
||
按 ownership_type 筛选系统或用户技能;q 对名称和描述进行不区分大小写的字面子串搜索。
|
||
筛选在游标分页前执行;切换类型或关键词时应清空 cursor。limit 控制单页数量,next_cursor 为空表示无后续页。
|
||
responses:
|
||
'200':
|
||
description: 查询Skill
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/SkillResource'
|
||
next_cursor:
|
||
type: string
|
||
required:
|
||
- items
|
||
- next_cursor
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: ownership_type
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- system
|
||
- user
|
||
- name: q
|
||
in: query
|
||
schema:
|
||
type: string
|
||
- name: cursor
|
||
in: query
|
||
schema:
|
||
type: string
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 500
|
||
default: 200
|
||
post:
|
||
summary: 创建Skill
|
||
responses:
|
||
'200':
|
||
description: 创建Skill
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SkillResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
package:
|
||
type: string
|
||
format: binary
|
||
description: 最多 500 MiB ZIP,解包最多 1 GiB。
|
||
metadata:
|
||
type: string
|
||
description: JSON 字符串,包含 tag_ids 和 grants。
|
||
required:
|
||
- package
|
||
/api/admin/v1/skills/{id}:
|
||
get:
|
||
summary: 读取Skill
|
||
responses:
|
||
'200':
|
||
description: 读取Skill
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SkillResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
put:
|
||
summary: 更新Skill
|
||
responses:
|
||
'200':
|
||
description: 更新Skill
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SkillResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SkillInput'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
delete:
|
||
summary: 删除Skill
|
||
responses:
|
||
'204':
|
||
description: 删除Skill
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/skills/{id}/enabled:
|
||
patch:
|
||
summary: 启停技能
|
||
description: 支持管理员创建和资源包导入的技能。手动启停设置会保留到后续资源包更新。
|
||
responses:
|
||
'200':
|
||
description: 启停Skill
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SkillResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
enabled:
|
||
type: boolean
|
||
required:
|
||
- enabled
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/experts:
|
||
get:
|
||
summary: 查询Expert
|
||
description: |
|
||
按 ownership_type 筛选系统或用户专家;q 对名称、描述和提示词进行不区分大小写的字面子串搜索。
|
||
筛选在游标分页前执行;切换类型或关键词时应清空 cursor。limit 控制单页数量,next_cursor 为空表示无后续页。
|
||
responses:
|
||
'200':
|
||
description: 查询Expert
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ExpertResource'
|
||
next_cursor:
|
||
type: string
|
||
required:
|
||
- items
|
||
- next_cursor
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: ownership_type
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- system
|
||
- user
|
||
- name: q
|
||
in: query
|
||
schema:
|
||
type: string
|
||
- name: cursor
|
||
in: query
|
||
schema:
|
||
type: string
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 500
|
||
default: 200
|
||
post:
|
||
summary: 创建Expert
|
||
responses:
|
||
'200':
|
||
description: 创建Expert
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpertResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpertInput'
|
||
multipart/form-data:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpertAvatarForm'
|
||
/api/admin/v1/experts/{id}:
|
||
get:
|
||
summary: 读取Expert
|
||
responses:
|
||
'200':
|
||
description: 读取Expert
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpertResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
put:
|
||
summary: 更新Expert
|
||
responses:
|
||
'200':
|
||
description: 更新Expert
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpertResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpertInput'
|
||
multipart/form-data:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpertAvatarForm'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
delete:
|
||
summary: 删除Expert
|
||
responses:
|
||
'204':
|
||
description: 删除Expert
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/experts/{id}/avatar:
|
||
get:
|
||
summary: 读取专家头像
|
||
description: 需要管理员登录。avatar_path 包含头像版本参数;支持已有资源包 WebP 头像及管理员上传的 PNG、JPEG、WebP。
|
||
parameters:
|
||
- {name: id, in: path, required: true, schema: {type: string, format: uuid}}
|
||
responses:
|
||
'200':
|
||
description: 专家头像图片
|
||
content:
|
||
image/png: {schema: {type: string, format: binary}}
|
||
image/jpeg: {schema: {type: string, format: binary}}
|
||
image/webp: {schema: {type: string, format: binary}}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'403': {$ref: '#/components/responses/ResourceError403'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'500': {$ref: '#/components/responses/ResourceError500'}
|
||
'502': {$ref: '#/components/responses/ResourceError502'}
|
||
/api/admin/v1/experts/{id}/enabled:
|
||
patch:
|
||
summary: 启停Expert
|
||
description: 支持管理员创建和资源包导入的专家。手动启停设置会保留到后续资源包更新。
|
||
responses:
|
||
'200':
|
||
description: 启停Expert
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpertResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
enabled:
|
||
type: boolean
|
||
required:
|
||
- enabled
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/connectors:
|
||
get:
|
||
summary: 查询Connector
|
||
description: |
|
||
按 ownership_type 筛选系统或用户连接器;q 对名称和描述进行不区分大小写的字面子串搜索。
|
||
筛选在游标分页前执行;切换类型或关键词时应清空 cursor。limit 控制单页数量,next_cursor 为空表示无后续页。
|
||
responses:
|
||
'200':
|
||
description: 查询Connector
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ConnectorResource'
|
||
next_cursor:
|
||
type: string
|
||
required:
|
||
- items
|
||
- next_cursor
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: ownership_type
|
||
in: query
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- system
|
||
- user
|
||
- name: q
|
||
in: query
|
||
schema:
|
||
type: string
|
||
- name: cursor
|
||
in: query
|
||
schema:
|
||
type: string
|
||
- name: limit
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 500
|
||
default: 200
|
||
post:
|
||
summary: 创建Connector
|
||
responses:
|
||
'200':
|
||
description: 创建Connector
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConnectorResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ConnectorInput'
|
||
required:
|
||
- name
|
||
- url
|
||
- authorization_mode
|
||
description: 创建 Connector,可在 credential 中同时配置集中认证凭证。连接器、凭证、标签和授权在同一事务中保存;Header 凭证保存后自动测试连接,测试失败保留配置。OAuth 可先保存凭证名称,再通过授权接口完成认证。不返回凭证秘密。
|
||
/api/admin/v1/connectors/{id}:
|
||
get:
|
||
summary: 读取Connector
|
||
responses:
|
||
'200':
|
||
description: 读取Connector
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConnectorResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
put:
|
||
summary: 更新Connector
|
||
responses:
|
||
'200':
|
||
description: 更新Connector
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConnectorResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConnectorInput'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
description: 编辑连接及集中认证凭证,携带连接 If-Match;修改既有凭证还需 credential.id 和 credential.revision。省略 credential 保留凭证,省略 http_headers 保留 Header;revoke=true 撤销指定凭证。支持仅提交 credential,资源包连接器同样支持,凭证不写入资源包覆盖字段。连接器与凭证保存失败时一起回滚。关键配置变更使旧凭证、目录和授权事务失效;Client Secret 轮换不使既有 Token 失效。
|
||
delete:
|
||
summary: 删除Connector
|
||
responses:
|
||
'204':
|
||
description: 删除Connector
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/connectors/{id}/enabled:
|
||
patch:
|
||
summary: 启停Connector
|
||
description: 支持管理员创建和资源包导入的连接器。手动启停设置会保留到后续资源包更新。
|
||
responses:
|
||
'200':
|
||
description: 启停Connector
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConnectorResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
enabled:
|
||
type: boolean
|
||
required:
|
||
- enabled
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/skills/{id}/package:
|
||
put:
|
||
summary: 替换技能包
|
||
responses:
|
||
'200':
|
||
description: 替换技能包
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SkillResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
package:
|
||
type: string
|
||
format: binary
|
||
description: 最多 500 MiB ZIP,解包最多 1 GiB。
|
||
metadata:
|
||
type: string
|
||
description: JSON 字符串,包含 tag_ids 和 grants。
|
||
required:
|
||
- package
|
||
get:
|
||
summary: 按当前权限下载技能包
|
||
responses:
|
||
'200':
|
||
description: 按当前权限下载技能包
|
||
content:
|
||
application/zip:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: sha256
|
||
in: query
|
||
schema:
|
||
type: string
|
||
description: 客户端清单记录的包摘要;与当前包不同返回 412。
|
||
/api/admin/v1/skills/{id}/manifest:
|
||
get:
|
||
summary: 读取技能正文
|
||
responses:
|
||
'200':
|
||
description: 读取技能正文
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
content:
|
||
type: string
|
||
revision:
|
||
type: integer
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/resources/authorization-subjects:
|
||
get:
|
||
summary: 查询实际授权对象
|
||
responses:
|
||
'200':
|
||
description: 查询实际授权对象
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
groups:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
parent_id:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
name:
|
||
type: string
|
||
users:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
email:
|
||
type: string
|
||
group_id:
|
||
type: string
|
||
format: uuid
|
||
description: 授权选择器展示的所属分组;未加入其他分组时为根 UUID。
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
/api/admin/v1/resources/{type}/{id}/grants:
|
||
get:
|
||
summary: 读取或更新授权
|
||
responses:
|
||
'200':
|
||
description: 读取或更新授权
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
grants:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
revision:
|
||
type: integer
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: type
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
put:
|
||
summary: 读取或更新授权
|
||
responses:
|
||
'200':
|
||
description: 读取或更新授权
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
grants:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
revision:
|
||
type: integer
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
grants:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
required:
|
||
- grants
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: type
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/tags:
|
||
get:
|
||
summary: 查询标签
|
||
responses:
|
||
'200':
|
||
description: 查询标签
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceTag'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
post:
|
||
summary: 创建标签
|
||
responses:
|
||
'200':
|
||
description: 创建标签
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceTag'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
required:
|
||
- name
|
||
/api/admin/v1/tags/{id}:
|
||
put:
|
||
summary: 重命名标签
|
||
responses:
|
||
'200':
|
||
description: 重命名标签
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceTag'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
required:
|
||
- name
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
delete:
|
||
summary: 删除标签
|
||
responses:
|
||
'204':
|
||
description: 删除标签
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/experts/{id}/copy:
|
||
post:
|
||
summary: 复制为未授权且禁用的专家
|
||
responses:
|
||
'200':
|
||
description: 复制为未授权且禁用的专家
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpertResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
required:
|
||
- name
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/experts/{id}/preview:
|
||
post:
|
||
summary: 以指定用户预览最终资源清单
|
||
responses:
|
||
'200':
|
||
description: 以指定用户预览最终资源清单
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ExpertManifest'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
expert_id:
|
||
type: string
|
||
format: uuid
|
||
rule_ids:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
skill_ids:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
connector_bindings:
|
||
type: object
|
||
additionalProperties:
|
||
type: string
|
||
format: uuid
|
||
required:
|
||
- user_id
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/connectors/{id}/tools/{toolID}:
|
||
patch:
|
||
summary: 配置工具启停和积分
|
||
description: 无认证/集中认证可创建或更新本地配置;独立认证仅兼容更新已有工具配置的开关,不新增配置且不允许非零单价。查询工具不会创建配置记录。兼容省略 name 的旧请求:已有配置按 ID 更新,无认证/集中认证的新工具按返回 ID 实时反查名称。未配置默认开启、单价为零,仅集中认证允许非零单价。
|
||
responses:
|
||
'200':
|
||
description: 配置工具启停和积分
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/MCPToolSetting'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 256
|
||
description: 可省略以兼容旧客户端;无认证/集中认证的新工具可按查询返回的 ID 实时反查名称。
|
||
enabled:
|
||
type: boolean
|
||
credits_per_call:
|
||
type: number
|
||
minimum: 0
|
||
required:
|
||
- enabled
|
||
- credits_per_call
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: toolID
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/connectors/{id}/test:
|
||
post:
|
||
summary: 执行真实 MCP 握手与全量工具发现
|
||
responses:
|
||
'200':
|
||
description: 执行真实 MCP 握手与全量工具发现
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
connection_status:
|
||
type: string
|
||
tool_count:
|
||
type: integer
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
description: 独立认证必须使用包含 credential_id 的接口,否则返回 400 credential_selection_required。连接级工具适用于 none / centralized;集中测试仅限管理员。
|
||
/api/admin/v1/connectors/{id}/tools:
|
||
get:
|
||
summary: 实时读取认证上下文的工具目录
|
||
description: 每次实时请求远端 MCP 获取工具定义,叠加本地开关和单价,包含禁用工具;没有配置记录时默认开启、单价为零。独立认证保留历史工具 ID 和启停配置,不新增配置且单价固定为零。响应为 private, no-store,远端失败不返回旧目录。
|
||
responses:
|
||
'200':
|
||
description: 读取认证上下文的工具目录
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/MCPTool'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/connectors/{id}/oauth/authorizations:
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
post:
|
||
summary: 添加命名 OAuth 凭证,每次成功新建
|
||
responses:
|
||
'200':
|
||
description: 成功;不返回凭证秘密。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/OAuthAuthorization'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AuthorizationName'
|
||
/api/admin/v1/connector-authorizations/{id}:
|
||
get:
|
||
summary: 查询本人发起的授权事务状态
|
||
description: 保存凭证后自动测试连接并发现工具,测试尝试完成后返回 succeeded 和 credential_id;测试失败不影响授权成功,结果记录在凭证测试状态中。
|
||
responses:
|
||
'200':
|
||
description: 查询本人发起的授权事务状态
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/AuthorizationStatus'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/connectors/{id}/credentials:
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
get:
|
||
summary: 列出集中凭证元数据
|
||
responses:
|
||
'200':
|
||
description: 成功;不返回凭证秘密。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ConnectorCredential'
|
||
required:
|
||
- items
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
|
||
/api/admin/v1/connectors/{id}/credentials/{credential_id}:
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: credential_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
get:
|
||
summary: 读取指定凭证元数据及 ETag
|
||
responses:
|
||
'200':
|
||
description: 成功;不返回凭证秘密。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConnectorCredential'
|
||
headers:
|
||
ETag:
|
||
description: 凭证编辑版本。
|
||
schema:
|
||
type: string
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
|
||
/api/admin/v1/connectors/{id}/credentials/{credential_id}/oauth/authorizations:
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: credential_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
post:
|
||
summary: 重新授权指定凭证,成功后保持 ID 并失效原目录
|
||
responses:
|
||
'200':
|
||
description: 成功;不返回凭证秘密。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/OAuthAuthorization'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
schema:
|
||
type: string
|
||
description: 当前凭证 revision 的带双引号 ETag;冲突返回 412 revision_conflict。
|
||
/api/admin/v1/connectors/{id}/credentials/{credential_id}/test:
|
||
post:
|
||
summary: 执行真实 MCP 握手与全量工具发现
|
||
responses:
|
||
'200':
|
||
description: 执行真实 MCP 握手与全量工具发现
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
connection_status:
|
||
type: string
|
||
tool_count:
|
||
type: integer
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters: []
|
||
description: 操作明确指定的凭证上下文;校验连接、凭证、当前用户和配置版本。管理端工具只读上下文允许查看系统连接用户工具,不能代用户测试。
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: credential_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/connectors/{id}/credentials/{credential_id}/tools:
|
||
get:
|
||
summary: 实时读取认证上下文的工具目录
|
||
description: 每次实时请求远端 MCP 获取工具定义,叠加本地开关和单价,包含禁用工具;没有配置记录时默认开启、单价为零。独立认证保留历史工具 ID 和启停配置,不新增配置且单价固定为零。响应为 private, no-store,远端失败不返回旧目录。
|
||
responses:
|
||
'200':
|
||
description: 读取认证上下文的工具目录
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/MCPTool'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters: []
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: credential_id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/connectors/{id}/icon:
|
||
put:
|
||
summary: 上传连接图标
|
||
responses:
|
||
'200':
|
||
description: 更新连接图标
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ConnectorResource'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 上次读取返回的 ETag,例如 "1"。
|
||
schema:
|
||
type: string
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
icon:
|
||
type: string
|
||
format: binary
|
||
description: PNG/JPEG,最多 1 MiB,最多 4096×4096。
|
||
required:
|
||
- icon
|
||
description: 系统连接由管理员维护,个人连接由所有者维护;携带连接 If-Match。
|
||
get:
|
||
summary: 读取连接图标
|
||
responses:
|
||
'200':
|
||
description: 读取私有模板图标
|
||
content:
|
||
image/png:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/connectors/{id}/tool-contexts:
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
get:
|
||
summary: 列出系统连接的凭证工具上下文元数据
|
||
responses:
|
||
'200':
|
||
description: 成功;不返回凭证秘密。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ConnectorCredential'
|
||
required:
|
||
- items
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
$ref: '#/components/responses/ResourceError401'
|
||
'403':
|
||
$ref: '#/components/responses/ResourceError403'
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
$ref: '#/components/responses/ResourceError409'
|
||
'412':
|
||
$ref: '#/components/responses/ResourceError412'
|
||
'428':
|
||
$ref: '#/components/responses/ResourceError428'
|
||
'500':
|
||
$ref: '#/components/responses/ResourceError500'
|
||
'502':
|
||
$ref: '#/components/responses/ResourceError502'
|
||
/api/admin/v1/endpoints:
|
||
get:
|
||
summary: 查询所有用户的客户端设备登记记录
|
||
description: 一行对应 (user_id,machine_id) 的一条设备登记记录,字段为当前登记值。以 endpoints 为主表关联 users,不依赖会话或轮次上报。默认无时间限制,包含已撤销登记和已删除用户的记录;按最近活动降序(空值最后)、创建时间降序、ID 降序分页。最近活动为设备记录中 last_seen_at 与 last_reported_at 较新的时间,不能据此推断实时在线。每次读取 page_size+1 判断 has_next,不执行列表总数
|
||
COUNT。只返回展示字段,不返回执行公钥或授权信息。
|
||
parameters:
|
||
- in: query
|
||
name: query
|
||
description: 对使用者姓名、邮箱、设备名称、别名、客户端名称及设备 ID 做不区分大小写的字面子串搜索。
|
||
schema:
|
||
type: string
|
||
maxLength: 200
|
||
- in: query
|
||
name: user_id
|
||
description: 按所属用户精确筛选。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- in: query
|
||
name: platform
|
||
description: 操作系统类型,不区分大小写精确匹配。
|
||
schema:
|
||
type: string
|
||
maxLength: 64
|
||
- in: query
|
||
name: client_type
|
||
description: 客户端类型,不区分大小写精确匹配。
|
||
schema:
|
||
type: string
|
||
maxLength: 32
|
||
- in: query
|
||
name: client_version
|
||
description: 客户端版本,精确匹配。
|
||
schema:
|
||
type: string
|
||
maxLength: 64
|
||
- in: query
|
||
name: arch
|
||
description: CPU 架构,不区分大小写精确匹配。
|
||
schema:
|
||
type: string
|
||
maxLength: 32
|
||
- in: query
|
||
name: status
|
||
description: 登记状态,不代表实时在线。
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- active
|
||
- revoked
|
||
- in: query
|
||
name: from
|
||
description: 最近活动时间下界,包含;不提供时不限制。
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- in: query
|
||
name: until
|
||
description: 最近活动时间上界,不包含;不提供时不限制。
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- in: query
|
||
name: page
|
||
schema:
|
||
type: integer
|
||
default: 1
|
||
minimum: 1
|
||
maximum: 1000000
|
||
- in: query
|
||
name: page_size
|
||
schema:
|
||
type: integer
|
||
default: 50
|
||
minimum: 1
|
||
maximum: 500
|
||
responses:
|
||
'200':
|
||
description: '登记记录页,Cache-Control: private, no-store'
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- items
|
||
- page
|
||
- page_size
|
||
- has_next
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ClientDevice'
|
||
page:
|
||
type: integer
|
||
page_size:
|
||
type: integer
|
||
has_next:
|
||
type: boolean
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 需要管理员权限
|
||
'503':
|
||
description: 设备清单暂不可用
|
||
/api/admin/v1/endpoints/overview:
|
||
get:
|
||
summary: 统计客户端设备登记记录及其分布
|
||
description: 筛选口径与设备列表一致,默认覆盖全部登记记录。total 按 (user_id,machine_id) 记录计数,users 按 user_id 去重;三个分布均按设备登记记录计数,不是会话数,也不是按物理设备去重的安装量。不接受分页参数。
|
||
parameters:
|
||
- in: query
|
||
name: query
|
||
description: 对使用者姓名、邮箱、设备名称、别名、客户端名称及设备 ID 做不区分大小写的字面子串搜索。
|
||
schema:
|
||
type: string
|
||
maxLength: 200
|
||
- in: query
|
||
name: user_id
|
||
description: 按所属用户精确筛选。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- in: query
|
||
name: platform
|
||
description: 操作系统类型,不区分大小写精确匹配。
|
||
schema:
|
||
type: string
|
||
maxLength: 64
|
||
- in: query
|
||
name: client_type
|
||
description: 客户端类型,不区分大小写精确匹配。
|
||
schema:
|
||
type: string
|
||
maxLength: 32
|
||
- in: query
|
||
name: client_version
|
||
description: 客户端版本,精确匹配。
|
||
schema:
|
||
type: string
|
||
maxLength: 64
|
||
- in: query
|
||
name: arch
|
||
description: CPU 架构,不区分大小写精确匹配。
|
||
schema:
|
||
type: string
|
||
maxLength: 32
|
||
- in: query
|
||
name: status
|
||
description: 登记状态,不代表实时在线。
|
||
schema:
|
||
type: string
|
||
enum:
|
||
- active
|
||
- revoked
|
||
- in: query
|
||
name: from
|
||
description: 最近活动时间下界,包含;不提供时不限制。
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
- in: query
|
||
name: until
|
||
description: 最近活动时间上界,不包含;不提供时不限制。
|
||
schema:
|
||
type: string
|
||
format: date-time
|
||
responses:
|
||
'200':
|
||
description: '登记统计,Cache-Control: private, no-store'
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ClientDeviceOverview'
|
||
'400':
|
||
description: 参数不合法
|
||
'401':
|
||
description: 未登录
|
||
'403':
|
||
description: 需要管理员权限
|
||
'503':
|
||
description: 设备清单暂不可用
|
||
/api/admin/v1/kb:
|
||
get:
|
||
summary: 分页查询知识库
|
||
description: 仅返回 ownership_type 对应的系统或用户知识库;q 对名称和描述做不区分大小写的包含匹配。向量模型可选,未配置时仅启用 lexical 全文检索。
|
||
parameters:
|
||
- {name: ownership_type, in: query, schema: {type: string, enum: [system, user]}}
|
||
- {name: q, in: query, schema: {type: string}}
|
||
- {name: cursor, in: query, schema: {type: string}}
|
||
- {name: limit, in: query, schema: {type: integer, minimum: 1, maximum: 500, default: 200}}
|
||
responses:
|
||
'200':
|
||
description: 知识库列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [items, next_cursor]
|
||
properties:
|
||
items: {type: array, items: {$ref: '#/components/schemas/Kb'}}
|
||
next_cursor: {type: string}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
post:
|
||
summary: 创建知识库
|
||
description: 后端自动选择可用的系统 embedding 模型;存在可用模型时自动启用向量检索,否则仅使用全文检索。无需配置知识库向量模型。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbInput'}
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [metadata, avatar]
|
||
properties:
|
||
metadata:
|
||
type: string
|
||
description: JSON 字符串,字段与 application/json 请求一致。
|
||
avatar:
|
||
type: string
|
||
format: binary
|
||
description: 必须且仅上传一个 PNG、JPEG 或 WebP 图片文件,最多 1 MiB;不修改图标时使用 application/json。
|
||
encoding:
|
||
metadata: {contentType: application/json}
|
||
avatar: {contentType: 'image/png, image/jpeg, image/webp'}
|
||
responses:
|
||
'200':
|
||
description: 已创建
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Kb'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'409': {$ref: '#/components/responses/ResourceError409'}
|
||
/api/admin/v1/kb/{id}/images/upload:
|
||
parameters: [{$ref: '#/components/parameters/ResourceID'}]
|
||
post:
|
||
summary: 上传知识库正文图片
|
||
description: 需要管理员会话,仅允许上传系统知识库图片;个人知识库在管理端只读。 使用 multipart/form-data 的 file 字段上传一张图片,最多 32 MiB、2500 万像素,支持 PNG、JPEG、GIF、WebP;按真实内容完整解码校验,拒绝 SVG。图片按知识库和内容摘要存入对象存储,不新增关联表。返回的 url 及 markdown 可写入文档正文,读取时仍检查当前权限。此操作不创建或修改文档。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [file]
|
||
properties:
|
||
file: {type: string, format: binary}
|
||
responses:
|
||
'201':
|
||
description: 图片已保存;重复上传相同图片返回同一知识库内的相同地址。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [name, url, mime_type, size_bytes, markdown]
|
||
properties:
|
||
name: {type: string, description: 内容摘要加真实图片扩展名}
|
||
url: {type: string, description: 受权限保护的 /api/kb/<id>/assets/<name> 相对地址}
|
||
mime_type: {type: string, enum: [image/png, image/jpeg, image/gif, image/webp]}
|
||
size_bytes: {type: integer, minimum: 1, maximum: 33554432}
|
||
markdown: {type: string, description: 可直接插入正文的 Markdown 图片语法}
|
||
'400': {description: 无效图片、文件超限或 multipart 字段不合法}
|
||
'401': {description: 未登录或凭证失效}
|
||
'403': {description: 无正文写权限或非管理员调用管理端接口}
|
||
'404': {description: 知识库不存在或不可访问}
|
||
'409': {description: 知识库不允许编辑}
|
||
'503': {description: 未配置知识库对象存储}
|
||
/api/admin/v1/kb/{id}/avatar:
|
||
parameters: [{$ref: '#/components/parameters/ResourceID'}]
|
||
get:
|
||
summary: 读取知识库图标
|
||
description: 需要管理员登录。返回 PNG、JPEG 或 WebP 原图;不公开对象存储地址。
|
||
responses:
|
||
'200':
|
||
description: 知识库图标
|
||
content:
|
||
image/png:
|
||
schema: {type: string, format: binary}
|
||
image/jpeg:
|
||
schema: {type: string, format: binary}
|
||
image/webp:
|
||
schema: {type: string, format: binary}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
/api/admin/v1/kb/{id}:
|
||
parameters: [{$ref: '#/components/parameters/ResourceID'}]
|
||
get:
|
||
summary: 读取知识库详情
|
||
responses:
|
||
'200':
|
||
description: 知识库详情
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Kb'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
put:
|
||
summary: 更新知识库
|
||
description: 更新名称、描述、标签和 fusion_config。向量模型由后端自动选择,学习时重新检查可用性,不作为知识库配置项。
|
||
parameters: [{$ref: '#/components/parameters/IfMatch'}]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbInput'}
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [metadata, avatar]
|
||
properties:
|
||
metadata:
|
||
type: string
|
||
description: JSON 字符串,字段与 application/json 请求一致。
|
||
avatar:
|
||
type: string
|
||
format: binary
|
||
description: 必须且仅上传一个 PNG、JPEG 或 WebP 图片文件,最多 1 MiB;不修改图标时使用 application/json。
|
||
encoding:
|
||
metadata: {contentType: application/json}
|
||
avatar: {contentType: 'image/png, image/jpeg, image/webp'}
|
||
responses:
|
||
'200':
|
||
description: 已更新
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Kb'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'412': {$ref: '#/components/responses/ResourceError412'}
|
||
delete:
|
||
summary: 删除知识库
|
||
description: 业务层级联硬删除文档与全部 chunk;不依赖数据库外键。
|
||
parameters: [{$ref: '#/components/parameters/IfMatch'}]
|
||
responses:
|
||
'204': {description: 已删除}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'412': {$ref: '#/components/responses/ResourceError412'}
|
||
/api/admin/v1/kb/{id}/enabled:
|
||
parameters: [{$ref: '#/components/parameters/ResourceID'}]
|
||
patch:
|
||
summary: 启用或停用知识库
|
||
parameters: [{$ref: '#/components/parameters/IfMatch'}]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [enabled]
|
||
properties:
|
||
enabled: {type: boolean}
|
||
responses:
|
||
'200':
|
||
description: 已更新
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/Kb'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'412': {$ref: '#/components/responses/ResourceError412'}
|
||
/api/admin/v1/kb/search:
|
||
post:
|
||
summary: 检索知识库分片
|
||
description: 检索通道由知识库绑定的可用向量模型自动决定。绑定且维度有效时执行 lexical+vector weighted RRF;未绑定时只执行 lexical;向量通道运行时失败时该知识库降级为 lexical 并返回 degraded。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbSearchInput'}
|
||
responses:
|
||
'200':
|
||
description: 检索响应,包含实际通道、融合参数、降级与告警
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbSearchResponse'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
/api/admin/v1/kb/{id}/embedding-model/switch:
|
||
parameters:
|
||
- {$ref: '#/components/parameters/ResourceID'}
|
||
- {$ref: '#/components/parameters/IfMatch'}
|
||
post:
|
||
summary: 切换或解绑知识库向量模型
|
||
deprecated: true
|
||
description: 目标模型必须可用且与当前模型不同。model_id 为空时清空绑定和历史向量,后台同步会将该知识库视为未绑定并自动重新选择可用向量模型,不提供关闭向量检索的持久配置项;非空时更新模型、清空旧向量并创建 rebuild_model 异步任务。全文检索始终执行。旧模型向量在事务提交前全部清空,不会继续参与检索。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
embedding_model_id: {type: [string, 'null'], format: uuid, description: 首选字段;null 表示解绑并清空向量,后续同步会自动重新绑定可用模型。}
|
||
model_id: {type: string, format: uuid, deprecated: true, description: 兼容旧调用;embedding_model_id 优先。}
|
||
responses:
|
||
'200': {description: 已更新并创建向量重建任务, content: {application/json: {schema: {$ref: '#/components/schemas/Kb'}}}}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'409': {$ref: '#/components/responses/ResourceError409'}
|
||
'412': {$ref: '#/components/responses/ResourceError412'}
|
||
'428': {$ref: '#/components/responses/ResourceError428'}
|
||
/api/admin/v1/kb/{id}/index/rebuild:
|
||
parameters:
|
||
- {$ref: '#/components/parameters/ResourceID'}
|
||
- {$ref: '#/components/parameters/IfMatch'}
|
||
post:
|
||
summary: 重建知识库索引
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [operation]
|
||
properties:
|
||
operation:
|
||
type: string
|
||
enum: [learn, relearn, rebuild_parse, rebuild_lexical, rebuild_vector, rebuild_model]
|
||
model_id: {type: string, format: uuid, description: 仅 rebuild_model 使用}
|
||
responses:
|
||
'202': {description: 已进入索引任务队列, content: {application/json: {schema: {$ref: '#/components/schemas/Kb'}}}}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'409': {$ref: '#/components/responses/ResourceError409'}
|
||
'412': {$ref: '#/components/responses/ResourceError412'}
|
||
'428': {$ref: '#/components/responses/ResourceError428'}
|
||
/api/admin/v1/kb/{id}/documents:
|
||
parameters: [{$ref: '#/components/parameters/ResourceID'}]
|
||
get:
|
||
summary: 查询知识库文档
|
||
responses:
|
||
'200':
|
||
description: 文档列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [items]
|
||
properties:
|
||
items: {type: array, items: {$ref: '#/components/schemas/KbDocument'}}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
post:
|
||
summary: 添加并学习文档
|
||
description: 文档必须属于路径中的知识库。提交后立即返回 pending 文档,并创建异步学习任务完成切分、全文索引和可选向量写入。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbDocumentInput'}
|
||
responses:
|
||
'202':
|
||
description: 已创建并进入学习队列
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbDocument'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
/api/admin/v1/kb/{id}/documents/delete:
|
||
parameters: [{$ref: '#/components/parameters/ResourceID'}]
|
||
post:
|
||
summary: 删除知识库文档或文件夹(支持多个 ID)
|
||
description: ids 去重后最多 200 项,文件夹删除覆盖子树。协作写入须逐项提供 expected_revisions,全部归属与版本校验通过后执行。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbDocumentDeleteInput'}
|
||
responses:
|
||
'200': {description: 操作结果, content: {application/json: {schema: {$ref: '#/components/schemas/KbDocumentOperationResult'}}}}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'403': {description: 无写入权限}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
'412': {description: 文档版本已变化}
|
||
'428': {description: 缺少文档版本}
|
||
/api/admin/v1/kb/{id}/documents/move:
|
||
parameters: [{$ref: '#/components/parameters/ResourceID'}]
|
||
post:
|
||
summary: 移动知识库文档树节点(支持多个 ID)
|
||
description: 将文件夹或文档移动到指定父节点,并按前后相邻节点计算排序。不能移动到自身或子孙节点下。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbDocumentMoveInput'}
|
||
responses:
|
||
'200':
|
||
description: 已移动
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbDocumentOperationResult'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
/api/admin/v1/kb/{id}/documents/{documentId}:
|
||
parameters:
|
||
- {$ref: '#/components/parameters/ResourceID'}
|
||
- {name: documentId, in: path, required: true, schema: {type: string, format: uuid}}
|
||
get:
|
||
summary: 读取文档
|
||
responses:
|
||
'200':
|
||
description: 文档详情
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbDocument'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
put:
|
||
summary: 更新文档并重新学习
|
||
description: 保留文档所属知识库边界,取消旧学习任务并创建 relearn 异步任务;响应文档状态为 pending。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbDocumentInput'}
|
||
responses:
|
||
'202':
|
||
description: 已更新并进入重新学习队列
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/KbDocument'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
|
||
/api/admin/v1/kb/{id}/documents/restudy:
|
||
parameters:
|
||
- {$ref: '#/components/parameters/ResourceID'}
|
||
post:
|
||
summary: 批量重新学习知识库文档
|
||
description: 仅系统知识库可写。ID 去重后最多 200 个,逐项校验知识库归属;文件夹不执行学习。部分失败不回滚成功项。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [ids]
|
||
properties:
|
||
ids:
|
||
type: array
|
||
minItems: 1
|
||
maxItems: 200
|
||
items: {type: string, format: uuid}
|
||
description: 待重新学习的文档 ID,单条操作也传数组
|
||
responses:
|
||
'202':
|
||
description: 已处理请求,成功项进入现有学习流程,失败项附带原因
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [succeeded, failed]
|
||
properties:
|
||
succeeded:
|
||
type: array
|
||
items: {type: string, format: uuid}
|
||
failed:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required: [id, reason]
|
||
properties:
|
||
id: {type: string}
|
||
reason: {type: string}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
/api/admin/v1/kb/{id}/documents/{documentId}/chunks:
|
||
parameters:
|
||
- {$ref: '#/components/parameters/ResourceID'}
|
||
- {name: documentId, in: path, required: true, schema: {type: string, format: uuid}}
|
||
get:
|
||
summary: 查询文档分片
|
||
responses:
|
||
'200':
|
||
description: 分片列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [items]
|
||
properties:
|
||
items: {type: array, items: {$ref: '#/components/schemas/KbChunk'}}
|
||
'401': {$ref: '#/components/responses/ResourceError401'}
|
||
'404': {$ref: '#/components/responses/ResourceError404'}
|
||
/api/admin/v1/environments:
|
||
get:
|
||
summary: 查询环境列表
|
||
description: '默认隐藏已确认删除和已离线归档的环境,二者均可按 deleted 查看;在线等待删除和清理失败仍显示。可按host_id精确筛选宿主;筛选先于排序和分页。状态与页面目标代次一致。列表不返回 usage 和 usage_stale,资源使用数据仅在详情返回。按实际 CPU 核数或内存字节排序,未上报、过期超过 90 秒及非运行实例排最后;相同占用按创建时间、ID 降序。所有响应使用 Cache-Control: no-store。'
|
||
responses:
|
||
'200':
|
||
description: 成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentList'
|
||
'400':
|
||
description: 请求参数、字段或大小无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'401':
|
||
description: 登录凭据无效或过期。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'403':
|
||
description: 缺少管理员角色或对应 environment scope。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'404':
|
||
description: 资源不存在或不属于当前用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'409':
|
||
description: 版本、幂等键、状态、计费或宿主准入冲突;响应 error.code 区分原因。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'500':
|
||
description: 内部存储或服务错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
parameters:
|
||
- name: host_id
|
||
in: query
|
||
description: 精确筛选宿主;格式为UUID,不存在的宿主返回空列表,重复或无效值返回400。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: status
|
||
in: query
|
||
schema:
|
||
type: string
|
||
default: active
|
||
enum: [active, all, running, stopped, failed, pending_running, pending_stopped, pending_deleted, deleted]
|
||
- name: sort
|
||
in: query
|
||
schema:
|
||
type: string
|
||
default: newest
|
||
enum: [newest, cpu_desc, cpu_asc, memory_desc, memory_asc]
|
||
- name: page
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
- name: page_size
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
maximum: 100
|
||
/api/admin/v1/system-images:
|
||
get:
|
||
summary: 列出未下架的系统镜像
|
||
responses:
|
||
'200':
|
||
description: 查询或修改成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items: {type: array, items: {$ref: '#/components/schemas/SystemImage'}}
|
||
'403': {description: 需要管理员权限。}
|
||
/api/admin/v1/system-images/pull:
|
||
post:
|
||
summary: 在线拉取系统镜像
|
||
parameters:
|
||
- {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [display_name, upstream]
|
||
properties:
|
||
display_name: {type: string, minLength: 1, maxLength: 128}
|
||
upstream: {type: string}
|
||
responses:
|
||
'202':
|
||
description: 任务已持久化,轮询镜像详情获取进度。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SystemImage'
|
||
'403': {description: 需要管理员权限。}
|
||
'409': {description: 来源重复、幂等冲突、正在导入或默认镜像受保护。}
|
||
/api/admin/v1/system-images/upload:
|
||
post:
|
||
summary: 上传 Docker 镜像包
|
||
parameters:
|
||
- {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
required: [display_name, file]
|
||
properties:
|
||
display_name: {type: string, minLength: 1, maxLength: 128}
|
||
file: {type: string, format: binary}
|
||
responses:
|
||
'202':
|
||
description: 任务已持久化,轮询镜像详情获取进度。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SystemImage'
|
||
'403': {description: 需要管理员权限。}
|
||
'409': {description: 来源重复、幂等冲突、正在导入或默认镜像受保护。}
|
||
'413': {description: 镜像包超过大小限制。}
|
||
/api/admin/v1/system-images/{id}:
|
||
parameters:
|
||
- {name: id, in: path, required: true, schema: {type: string, format: uuid}}
|
||
get:
|
||
summary: 查询单个镜像和阶段进度
|
||
responses:
|
||
'200':
|
||
description: 查询或修改成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SystemImage'
|
||
'403': {description: 需要管理员权限。}
|
||
patch:
|
||
summary: 修改镜像展示名称
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [display_name]
|
||
properties:
|
||
display_name: {type: string, minLength: 1, maxLength: 128}
|
||
responses:
|
||
'200':
|
||
description: 查询或修改成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/SystemImage'
|
||
'403': {description: 需要管理员权限。}
|
||
delete:
|
||
summary: 移除镜像目录项,已有实例不受影响
|
||
responses:
|
||
'204':
|
||
description: 已从目录移除。
|
||
'403': {description: 需要管理员权限。}
|
||
'409': {description: 来源重复、幂等冲突、正在导入或默认镜像受保护。}
|
||
/api/admin/v1/environment-images:
|
||
get:
|
||
summary: 列出 server 已同步的云环境镜像
|
||
responses:
|
||
'200':
|
||
description: 同步状态和 server 固定摘要引用。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
items: {type: array, items: {$ref: '#/components/schemas/EnvironmentImage'}}
|
||
'403': {description: 需要管理员权限。}
|
||
/api/admin/v1/environment-images/sync:
|
||
post:
|
||
summary: 将固定摘要镜像同步到 server 仓库
|
||
description: 异步准备完整镜像与已有架构,完成后宿主仅从 server 拉取。相同来源正在同步或已就绪时复用记录,失败可重试。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [image]
|
||
properties:
|
||
image: {type: string, description: 上游完整仓库引用和固定 sha256 摘要。}
|
||
additionalProperties: false
|
||
responses:
|
||
'202':
|
||
description: 已受理或已有同步记录。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/EnvironmentImage'}
|
||
'400': {description: 镜像引用无效。}
|
||
'403': {description: 需要管理员权限。}
|
||
/api/admin/v1/environments/{id}:
|
||
get:
|
||
summary: 查询环境详情
|
||
description: ' 所有响应使用 Cache-Control: no-store。'
|
||
responses:
|
||
'200':
|
||
description: 成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/Environment'
|
||
'400':
|
||
description: 请求参数、字段或大小无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'401':
|
||
description: 登录凭据无效或过期。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'403':
|
||
description: 缺少管理员角色或对应 environment scope。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'404':
|
||
description: 资源不存在或不属于当前用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'409':
|
||
description: 版本、幂等键、状态、计费或宿主准入冲突;响应 error.code 区分原因。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'500':
|
||
description: 内部存储或服务错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
delete:
|
||
summary: 删除运行实例并保留持久目录
|
||
description: '环境确认删除后不再下发目标;失败可用新request_key和当前generation重试,不执行数据purge。所有响应不缓存。'
|
||
responses:
|
||
'202':
|
||
description: 请求已接受;操作结果通过查询环境或操作列表获得。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentResult'
|
||
'400':
|
||
description: 请求参数、字段或大小无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'401':
|
||
description: 登录凭据无效或过期。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'403':
|
||
description: 缺少管理员角色或对应 environment scope。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'404':
|
||
description: 资源不存在或不属于当前用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'409':
|
||
description: 版本、幂等键、状态、计费或宿主准入冲突;响应 error.code 区分原因。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'500':
|
||
description: 内部存储或服务错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentChange'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/environments/{id}/runtime:
|
||
get:
|
||
summary: 查询环境的 runtime 版本与更新能力
|
||
description: 仅管理员可用;返回当前版本、server 最新版本、更新操作与停止要求,响应不缓存。
|
||
parameters:
|
||
- {name: id, in: path, required: true, schema: {type: string, format: uuid}}
|
||
responses:
|
||
'200':
|
||
description: 成功。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/EnvironmentRuntimeInfo'}
|
||
'401': {description: 未登录或凭据过期。}
|
||
'403': {description: 需要管理员权限。}
|
||
'404': {description: 环境不存在。}
|
||
/api/admin/v1/environments/{id}/runtime/upgrade:
|
||
post:
|
||
summary: 不重建容器更新环境的 runtime
|
||
description: 仅管理员可用。环境必须已确认停止,宿主支持独立更新;保留容器、目录与设备身份。version 省略时选择 server 当前最新版本,显式版本可回退到 server 已有版本。请求使用 generation 与 request_key 保证并发安全和幂等,响应不缓存。
|
||
parameters:
|
||
- {name: id, in: path, required: true, schema: {type: string, format: uuid}}
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/EnvironmentRuntimeUpgrade'}
|
||
responses:
|
||
'202':
|
||
description: 已受理,查询 runtime 或操作记录等待 succeeded/failed。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/EnvironmentResult'}
|
||
'400': {description: 参数、额外字段或版本格式无效,不允许传下载地址。}
|
||
'401': {description: 未登录或凭据过期。}
|
||
'403': {description: 需要管理员权限。}
|
||
'404': {description: 环境不存在。}
|
||
'409': {description: 未停止、代次或幂等冲突、宿主不可用、版本已相同或不支持更新。}
|
||
'503': {description: server 尚未配置 runtime 发行资源。}
|
||
/api/admin/v1/environments/{id}/operations:
|
||
get:
|
||
summary: 查询环境操作记录
|
||
description: ' 所有响应使用 Cache-Control: no-store。'
|
||
responses:
|
||
'200':
|
||
description: 成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentOperationList'
|
||
'400':
|
||
description: 请求参数、字段或大小无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'401':
|
||
description: 登录凭据无效或过期。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'403':
|
||
description: 缺少管理员角色或对应 environment scope。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'404':
|
||
description: 资源不存在或不属于当前用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'409':
|
||
description: 版本、幂等键、状态、计费或宿主准入冲突;响应 error.code 区分原因。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'500':
|
||
description: 内部存储或服务错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
- name: page
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
- name: page_size
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
maximum: 100
|
||
/api/admin/v1/environments/{id}/stop:
|
||
post:
|
||
summary: 停止环境
|
||
description: '当前代次确认停止后结束计费,但仍保留环境名额和数据。所有响应不缓存。'
|
||
responses:
|
||
'202':
|
||
description: 请求已接受;操作结果通过查询环境或操作列表获得。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentResult'
|
||
'400':
|
||
description: 请求参数、字段或大小无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'401':
|
||
description: 登录凭据无效或过期。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'403':
|
||
description: 缺少管理员角色或对应 environment scope。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'404':
|
||
description: 资源不存在或不属于当前用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'409':
|
||
description: 版本、幂等键、状态、计费或宿主准入冲突;响应 error.code 区分原因。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'500':
|
||
description: 内部存储或服务错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentChange'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/environment-specifications:
|
||
get:
|
||
summary: 读取全局云电脑规格目录
|
||
description: 仅管理员可读。返回完整有序列表和整表 revision,不分页、不缓存;已有环境不依赖此目录启动。
|
||
responses:
|
||
'200':
|
||
description: 全局规格目录。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: 'agent.yaml#/components/schemas/EnvironmentSpecificationCatalog'
|
||
'401':
|
||
description: 未登录。
|
||
'403':
|
||
description: 非管理员。
|
||
put:
|
||
summary: 原子替换全局云电脑规格目录
|
||
description: 提交完整 items 与读取时的 revision;最多 100 项,允许空数组关闭新建,不接受 null。新增项使用新的小写 UUID 和 version=0;已有项保留 id 与 version。CPU/内存改变时该项 version 递增,仅重排不变;每次成功提交 revision 递增。遗漏的项软删除,已删除 ID 不得复用。相同 CPU/内存组合或重复 ID 返回400,目录或条目版本冲突返回409 specifications_conflict,不部分保存。修改/删除不改写已有环境资源快照、计费资源或再次启动条件。所有响应不缓存。
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentSpecificationCatalogInput'
|
||
responses:
|
||
'200':
|
||
description: 保存后的完整目录,包含最新版本。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: 'agent.yaml#/components/schemas/EnvironmentSpecificationCatalog'
|
||
'400':
|
||
description: 规格、列表或版本字段无效。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/EnvironmentError'}
|
||
'401':
|
||
description: 未登录。
|
||
'403':
|
||
description: 非管理员。
|
||
'409':
|
||
description: specifications_conflict;重新加载目录后再编辑,禁止直接覆盖其他管理员的更新。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/EnvironmentError'}
|
||
/api/admin/v1/environment-hosts:
|
||
get:
|
||
summary: 查询宿主环境容量
|
||
description: ' 所有响应使用 Cache-Control: no-store。'
|
||
responses:
|
||
'200':
|
||
description: 成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentHostList'
|
||
'400':
|
||
description: 请求参数、字段或大小无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'401':
|
||
description: 登录凭据无效或过期。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'403':
|
||
description: 缺少管理员角色或对应 environment scope。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'404':
|
||
description: 资源不存在或不属于当前用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'409':
|
||
description: 版本、幂等键、状态、计费或宿主准入冲突;响应 error.code 区分原因。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'500':
|
||
description: 内部存储或服务错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
parameters:
|
||
- name: page
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
- name: page_size
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
maximum: 100
|
||
/api/admin/v1/environment-hosts/{id}/setup:
|
||
get:
|
||
summary: 读取宿主授权范围
|
||
description: 读取当前宿主的授权范围和镜像准备状态,不返回宿主 resource 或数量上限。默认镜像由服务端按架构准备;capacity 反映硬件报告,billing 是只读全局计费配置。调度开关独立保存。所有响应不缓存。
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentSetup'
|
||
'400':
|
||
description: 请求参数、字段或大小无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'401':
|
||
description: 登录凭据无效或过期。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'403':
|
||
description: 缺少管理员角色或对应 environment scope。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'404':
|
||
description: 资源不存在或不属于当前用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'409':
|
||
description: 版本、幂等键、状态、计费或宿主准入冲突;响应 error.code 区分原因。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'500':
|
||
description: 内部存储或服务错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
put:
|
||
summary: 原子保存宿主授权范围
|
||
description: 当前宿主独立保存授权范围,最后有效提交覆盖,不使用配置 revision。resource 和数量上限不再接受;计费到全局费用设置修改。允许 CPU/内存总规格超卖,不限制宿主或用户环境数量,不删除或停止现有环境。
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'200':
|
||
description: 成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentSetup'
|
||
'400':
|
||
description: 请求参数、字段或大小无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'401':
|
||
description: 登录凭据无效或过期。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'403':
|
||
description: 缺少管理员角色或对应 environment scope。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'404':
|
||
description: 资源不存在或不属于当前用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'409':
|
||
description: 版本、幂等键、状态、计费或宿主准入冲突;响应 error.code 区分原因。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'500':
|
||
description: 内部存储或服务错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentSetupInput'
|
||
/api/admin/v1/environment-hosts/{id}/scheduling:
|
||
patch:
|
||
summary: 设置是否允许分配新环境
|
||
description: '仅 active 宿主可修改。容量使用最新心跳上报的全部 CPU 和内存,无独立环境数量限制。关闭不停止已有环境;资源设置保存不会覆盖此状态。新接入默认关闭,启用后仍需预检、协议同步与心跳就绪。'
|
||
responses:
|
||
'200':
|
||
description: 成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentCapacity'
|
||
'400':
|
||
description: 请求参数、字段或大小无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'401':
|
||
description: 登录凭据无效或过期。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'403':
|
||
description: 缺少管理员角色或对应 environment scope。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'404':
|
||
description: 资源不存在或不属于当前用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'409':
|
||
description: 版本、幂等键、状态、计费或宿主准入冲突;响应 error.code 区分原因。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'500':
|
||
description: 内部存储或服务错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [enabled]
|
||
additionalProperties: false
|
||
properties:
|
||
enabled: {type: boolean}
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/environment-hosts/{id}:
|
||
put:
|
||
summary: 设置宿主调度开关(兼容旧接口)
|
||
deprecated: true
|
||
description: '仅保存 enabled;旧容量字段忽略,容量由 engine 最新心跳决定。新调用方使用 scheduling 接口。'
|
||
responses:
|
||
'200':
|
||
description: 成功。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentCapacity'
|
||
'400':
|
||
description: 请求参数、字段或大小无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'401':
|
||
description: 登录凭据无效或过期。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'403':
|
||
description: 缺少管理员角色或对应 environment scope。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'404':
|
||
description: 资源不存在或不属于当前用户。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'409':
|
||
description: 版本、幂等键、状态、计费或宿主准入冲突;响应 error.code 区分原因。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
'500':
|
||
description: 内部存储或服务错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentError'
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/EnvironmentCapacityInput'
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
/api/admin/v1/engine-host-enrollments:
|
||
post:
|
||
summary: 生成宿主安装命令
|
||
description: 仅管理员可用;无需填写参数,命令有效期 30 分钟,仅首次返回。服务器必须已安装双架构 engine 资源。脚本自动识别架构和宿主名称,使用默认数据目录,全部运行组件从本 server 下载。令牌仅以摘要保存,首次注册绑定公钥和架构。
|
||
requestBody:
|
||
required: false
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
additionalProperties: false
|
||
responses:
|
||
'201':
|
||
description: 待接入宿主及仅本次展示的安装命令
|
||
headers:
|
||
Cache-Control:
|
||
schema:
|
||
type: string
|
||
const: no-store
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- host_id
|
||
- command
|
||
- expires_at
|
||
properties:
|
||
host_id:
|
||
type: string
|
||
format: uuid
|
||
command:
|
||
type: string
|
||
description: 含一次性凭据的完整 shell 命令
|
||
version:
|
||
type: string
|
||
description: 本次安装锁定的发行版本
|
||
expires_at:
|
||
type: string
|
||
format: date-time
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
description: 未登录管理员
|
||
'403':
|
||
description: 非管理员或来源校验失败
|
||
'503':
|
||
description: HTTPS 地址或架构对应的安装发行物尚未准备好
|
||
/api/admin/v1/engine-upgrade:
|
||
get:
|
||
summary: 获取 engine 统一安装/升级命令
|
||
description: 返回锁定当前 server 发行版本的宿主升级命令,不创建宿主、不重新注册身份。安装与升级使用同一个 install.sh,命令在宿主手动执行后由 installer 提供操作选择,保留配置和数据;失败恢复旧版本。仅支持 Docker engine 且 Docker/gVisor 依赖未变化的升级。
|
||
responses:
|
||
'200':
|
||
description: 固定版本升级命令
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required: [version, command]
|
||
properties:
|
||
version:
|
||
type: string
|
||
command:
|
||
type: string
|
||
'401':
|
||
description: 未登录管理员
|
||
'403':
|
||
description: 非管理员
|
||
'503':
|
||
description: HTTPS 地址或双架构 Docker engine 发行资源不完整
|
||
/api/admin/v1/engine-hosts:
|
||
get:
|
||
summary: 分页查询宿主及最近预检报告
|
||
description: 不返回等待接入(pending)的宿主,total 同样排除这些记录。online 仅表示 90 秒内有签名心跳;prerequisites_met 只表示预检前置条件,不能据此接收工作负载。不会返回令牌、密钥或签名挑战。
|
||
parameters:
|
||
- name: page
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
default: 1
|
||
- name: page_size
|
||
in: query
|
||
schema:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 100
|
||
default: 20
|
||
responses:
|
||
'200':
|
||
description: 宿主列表
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
required:
|
||
- items
|
||
- total
|
||
- page
|
||
- page_size
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/EngineHost'
|
||
total:
|
||
type: integer
|
||
page:
|
||
type: integer
|
||
page_size:
|
||
type: integer
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
description: 未登录管理员
|
||
'403':
|
||
description: 非管理员
|
||
/api/admin/v1/engine-hosts/{id}/upgrade:
|
||
post:
|
||
summary: 下发宿主 engine 升级任务
|
||
description: 仅支持在线且声明 upgrade_protocol=1 的宿主。目标版本必须为 server 当前版本,按 vYYMMDDNN 比较且必须高于宿主版本;未知或测试版本使用统一安装脚本。相同目标的活动任务重复请求返回同一任务,其他目标冲突。通过签名心跳响应下发固定发行摘要;30 分钟未完成则标记失败,允许重试。已有容器不重启。
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema: {type: string, format: uuid}
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [version]
|
||
properties:
|
||
version: {type: string, description: 页面显示的目标版本,用于拒绝过期操作}
|
||
responses:
|
||
'202':
|
||
description: 已持久化的升级任务;重复请求返回已有任务
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/EngineUpgradeTask'}
|
||
'400': {$ref: '#/components/responses/ResourceError400'}
|
||
'401': {description: 未登录管理员}
|
||
'403': {description: 非管理员或来源校验失败}
|
||
'404': {description: 宿主不存在或已删除}
|
||
'409': {description: 离线、不支持远程升级、版本不可升级或已有其他任务}
|
||
'503': {description: 目标架构的升级资源不完整}
|
||
/api/admin/v1/engine-hosts/{id}/enrollment:
|
||
post:
|
||
summary: 为待接入宿主重新生成安装命令
|
||
description: 仅管理员可用。保持同一宿主记录,原命令立即失效,新命令有效期 30 分钟并锁定 server 当前发行版本。已接入、撤销或删除的宿主不允许重新生成。令牌仅保存摘要,返回值禁止缓存。
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
requestBody:
|
||
required: false
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
additionalProperties: false
|
||
responses:
|
||
'200':
|
||
$ref: '#/paths/~1api~1admin~1v1~1engine-host-enrollments/post/responses/201'
|
||
'400':
|
||
$ref: '#/components/responses/ResourceError400'
|
||
'401':
|
||
description: 未登录管理员
|
||
'403':
|
||
description: 非管理员或来源校验失败
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
description: 宿主已接入、撤销或删除
|
||
'503':
|
||
description: server 安装资源或地址尚未准备好
|
||
/api/admin/v1/engine-hosts/{id}:
|
||
delete:
|
||
summary: 撤销宿主接入
|
||
description: 同时失效待接入命令、宿主认证和当前挑战;保留墓碑,不卸载宿主程序或删除数据。重复撤销幂等。
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'204':
|
||
description: 已撤销
|
||
'401':
|
||
description: 未登录管理员
|
||
'403':
|
||
description: 非管理员或来源校验失败
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
/api/admin/v1/engine-hosts/{id}/record:
|
||
delete:
|
||
summary: 删除宿主记录
|
||
description: 移除管理列表中的宿主并撤销接入、停用调度;所有关联环境必须已确认删除,或已离线归档且宿主仍离线,否则返回 409。保留内部墓碑及历史关联,不卸载 engine 或清理宿主数据。重复删除幂等。
|
||
parameters:
|
||
- name: id
|
||
in: path
|
||
required: true
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
'204':
|
||
description: 已删除或记录不存在
|
||
'401':
|
||
description: 未登录管理员
|
||
'403':
|
||
description: 非管理员或来源校验失败
|
||
'404':
|
||
$ref: '#/components/responses/ResourceError404'
|
||
'409':
|
||
description: 宿主仍有关联环境或环境尚未清理完成
|
||
components:
|
||
securitySchemes:
|
||
KnowledgeAssetBearer:
|
||
type: http
|
||
scheme: bearer
|
||
BrowserSession:
|
||
type: apiKey
|
||
in: cookie
|
||
name: monkeyai_session
|
||
description: 任意有效浏览器登录会话,不要求管理员角色。
|
||
AdminSession:
|
||
type: apiKey
|
||
in: cookie
|
||
name: monkeyai_session
|
||
description: 管理后台登录后设置的 HttpOnly Session Cookie。
|
||
parameters:
|
||
ResourceID:
|
||
name: id
|
||
in: path
|
||
required: true
|
||
schema: {type: string, format: uuid}
|
||
IfMatch:
|
||
name: If-Match
|
||
in: header
|
||
required: true
|
||
description: 当前资源的ETag,用于知识库并发更新和删除。
|
||
schema: {type: string, example: '"1"'}
|
||
ProfileCSRF:
|
||
in: header
|
||
name: X-CSRF-Token
|
||
required: true
|
||
description: GET /api/auth/v1/profile 返回的令牌;修改密码后须使用响应中的新令牌。
|
||
schema: {type: string}
|
||
ModelID:
|
||
in: path
|
||
name: modelID
|
||
required: true
|
||
description: 模型 UUID。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
KeyID:
|
||
in: path
|
||
name: keyID
|
||
required: true
|
||
description: 调用密钥 UUID。
|
||
schema:
|
||
type: string
|
||
format: uuid
|
||
responses:
|
||
ProfileError:
|
||
description: 本人账户设置操作失败,具体原因见 error.code 和 error.message。
|
||
content:
|
||
application/json:
|
||
schema: {$ref: '#/components/schemas/ResourceError'}
|
||
ResourceError400:
|
||
description: 字段或关联无效
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceError'
|
||
ResourceError401:
|
||
description: 需要登录
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceError'
|
||
ResourceError403:
|
||
description: 无权操作
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceError'
|
||
ResourceError404:
|
||
description: 资源不存在或无权访问
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceError'
|
||
ResourceError409:
|
||
description: 名称或引用冲突
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceError'
|
||
ResourceError412:
|
||
description: 修订或技能包摘要已变化
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceError'
|
||
ResourceError428:
|
||
description: 缺少 If-Match
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceError'
|
||
ResourceError500:
|
||
description: 读取或保存失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceError'
|
||
ResourceError502:
|
||
description: 上游连接失败
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: '#/components/schemas/ResourceError'
|
||
BadRequest:
|
||
description: 请求参数或请求体无效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ErrorResponse"
|
||
Unauthorized:
|
||
description: 未登录或 Session 已失效。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ErrorResponse"
|
||
Forbidden:
|
||
description: 当前用户没有管理员权限。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ErrorResponse"
|
||
NotFound:
|
||
description: 指定资源不存在。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ErrorResponse"
|
||
InternalError:
|
||
description: 服务内部错误。
|
||
content:
|
||
application/json:
|
||
schema:
|
||
$ref: "#/components/schemas/ErrorResponse"
|
||
schemas:
|
||
BrandingSettingRecord:
|
||
type: object
|
||
required: [key, value, schema_version, updated_by_user_id, updated_at]
|
||
properties:
|
||
key:
|
||
type: string
|
||
enum: [branding]
|
||
value:
|
||
type: object
|
||
required: [workspace_name, product_name, logo_url]
|
||
properties:
|
||
workspace_name:
|
||
type: string
|
||
product_name:
|
||
type: string
|
||
logo_url:
|
||
type: string
|
||
description: 自定义 Logo 的绝对 URL;未设置时为空字符串。
|
||
schema_version:
|
||
type: integer
|
||
updated_by_user_id:
|
||
type: string
|
||
format: uuid
|
||
updated_at:
|
||
type: string
|
||
format: date-time
|
||
ClientDevice:
|
||
type: object
|
||
required:
|
||
- id
|
||
- user_id
|
||
- machine_id
|
||
- user_name
|
||
- user_email
|
||
- user_avatar_url
|
||
- alias
|
||
- client_type
|
||
- client_name
|
||
- locale
|
||
- system_locale
|
||
- timezone
|
||
- runtime_version
|
||
- engine_version
|
||
- user_deleted
|
||
- device_name
|
||
- platform
|
||
- os_version
|
||
- arch
|
||
- client_version
|
||
- status
|
||
- created_at
|
||
- updated_at
|
||
- last_seen_at
|
||
- last_reported_at
|
||
- last_active_at
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
machine_id:
|
||
type: string
|
||
format: uuid
|
||
user_name:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
user_email:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
user_avatar_url:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
alias:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
client_type:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
client_name:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
locale:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
system_locale:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
timezone:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
runtime_version:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
engine_version:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
user_deleted:
|
||
type: boolean
|
||
device_name:
|
||
type: string
|
||
platform:
|
||
type: string
|
||
os_version:
|
||
type: string
|
||
arch:
|
||
type: string
|
||
client_version:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum:
|
||
- active
|
||
- revoked
|
||
description: active 表示登记有效,不表示在线。
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
description: 首次创建登记记录时间,不等同于首次连接或首次对话。
|
||
updated_at:
|
||
type: string
|
||
format: date-time
|
||
last_seen_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
last_reported_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
last_active_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
description: GREATEST(last_seen_at,last_reported_at),两者均为空时为 null。
|
||
ClientDeviceOverview:
|
||
type: object
|
||
required:
|
||
- metric
|
||
- total
|
||
- users
|
||
- distributions
|
||
properties:
|
||
metric:
|
||
type: string
|
||
enum:
|
||
- devices
|
||
total:
|
||
type: integer
|
||
users:
|
||
type: integer
|
||
distributions:
|
||
type: object
|
||
required:
|
||
- client_type
|
||
- platform
|
||
- client_version
|
||
properties:
|
||
client_type:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required:
|
||
- value
|
||
- count
|
||
properties:
|
||
value:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
count:
|
||
type: integer
|
||
platform:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required:
|
||
- value
|
||
- count
|
||
properties:
|
||
value:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
count:
|
||
type: integer
|
||
client_version:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required:
|
||
- value
|
||
- count
|
||
properties:
|
||
value:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
count:
|
||
type: integer
|
||
ResourceImportUploadFile:
|
||
type: object
|
||
required: [name, size]
|
||
properties:
|
||
name: {type: string, description: ZIP 文件名或从 001 连续递增的分卷文件名}
|
||
size: {type: integer, format: int64, minimum: 1, maximum: 2147483648}
|
||
ResourceImportUpload:
|
||
type: object
|
||
required: [id, files, total_size, status, package_sha256, chunk_size, chunks, created_at, expires_at]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
files:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ResourceImportUploadFile'}
|
||
total_size: {type: integer, format: int64}
|
||
status: {type: string, enum: [uploading, ready, imported]}
|
||
package_sha256: {type: string, description: 封存后由服务端计算的完整 ZIP 摘要,上传期间为空}
|
||
chunk_size: {type: integer, const: 67108864}
|
||
chunks:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required: [index, size, sha256]
|
||
properties:
|
||
index: {type: integer, minimum: 0, maximum: 31}
|
||
size: {type: integer, format: int64}
|
||
sha256: {type: string}
|
||
created_at: {type: string, format: date-time}
|
||
expires_at: {type: string, format: date-time}
|
||
ResourceSectionResult:
|
||
type: object
|
||
required: [status, replayed]
|
||
properties:
|
||
status: {type: string, enum: [succeeded, failed]}
|
||
replayed: {type: boolean}
|
||
http_status: {type: integer}
|
||
error:
|
||
type: object
|
||
properties:
|
||
code: {type: string}
|
||
message: {type: string}
|
||
result: {type: object, description: Agent Preview或设计Plan,包含源release_id及资源计数}
|
||
ResourceImportInput:
|
||
type: object
|
||
required: [upload_id]
|
||
properties:
|
||
upload_id: {type: string, format: uuid}
|
||
package_sha256: {type: string}
|
||
plan_digest: {type: string}
|
||
discover_only: {type: boolean, description: 只发现分区,不生成计划,不能用于Apply}
|
||
sections:
|
||
type: array
|
||
minItems: 1
|
||
uniqueItems: true
|
||
items: {type: string, enum: [agent, design, knowledge]}
|
||
section_plan_digests:
|
||
type: object
|
||
additionalProperties: {type: string}
|
||
options:
|
||
type: object
|
||
properties:
|
||
confirm_final: {type: boolean, description: 确认导入时必须为 true}
|
||
accept_normalization: {type: boolean}
|
||
authorization_modes:
|
||
type: object
|
||
additionalProperties: {type: string, enum: [independent, centralized]}
|
||
FeedbackPage:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [items, total, page, page_size]
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Feedback'
|
||
total: {type: integer, format: int64, minimum: 0}
|
||
page: {type: integer, minimum: 1}
|
||
page_size: {type: integer, minimum: 1}
|
||
Feedback:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, user_id, category, content, platform, client_version, state, created_at, updated_at, attachments]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
user_id: {type: string, format: uuid}
|
||
user_name: {type: string, description: 提交反馈的用户名,仅管理员列表返回。}
|
||
user_email: {type: string, format: email, description: 提交反馈的邮箱,仅管理员列表返回。}
|
||
user_avatar_url: {type: [string, 'null'], description: 提交反馈用户的当前头像,仅管理员列表返回;为空或省略时使用默认头像。}
|
||
category: {type: string, enum: [bug, feature, experience, other]}
|
||
content: {type: string, maxLength: 5000}
|
||
rating: {type: [integer, 'null'], minimum: 1, maximum: 5}
|
||
platform: {type: string, enum: [desktop, mobile, web, other]}
|
||
client_version: {type: string, maxLength: 64}
|
||
state: {type: string, enum: [uploading, new, resolved, ignored, failed]}
|
||
request_id: {type: string}
|
||
created_at: {type: string, format: date-time}
|
||
updated_at: {type: string, format: date-time}
|
||
attachments:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/FeedbackAttachment'
|
||
FeedbackAttachment:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, feedback_id, mime_type, byte_size, width, height, sha256, state, downloadable, created_at]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
feedback_id: {type: string, format: uuid}
|
||
mime_type: {type: string, enum: [image/png, image/jpeg, image/webp]}
|
||
byte_size: {type: integer, format: int64, minimum: 1}
|
||
width: {type: integer, minimum: 1}
|
||
height: {type: integer, minimum: 1}
|
||
sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
|
||
state: {type: string, enum: [pending, ready, failed]}
|
||
downloadable: {type: boolean}
|
||
created_at: {type: string, format: date-time}
|
||
EmailAuthError:
|
||
type: object
|
||
required:
|
||
- error
|
||
properties:
|
||
error:
|
||
type: object
|
||
required:
|
||
- code
|
||
- message
|
||
properties:
|
||
code:
|
||
type: string
|
||
message:
|
||
type: string
|
||
EmailLoginMethods:
|
||
type: object
|
||
required:
|
||
- password_enabled
|
||
- email_code_enabled
|
||
- email_code_auto_registration_enabled
|
||
properties:
|
||
password_enabled:
|
||
type: boolean
|
||
description: 密码登录开关,未配置时默认 true,同时约束管理员和普通用户。
|
||
email_code_enabled:
|
||
type: boolean
|
||
description: 验证码登录开关,默认 false。
|
||
email_code_auto_registration_enabled:
|
||
type: boolean
|
||
description: 邮箱验证码自动注册开关,默认 false;客户端使用新邮箱通过验证码登录时自动创建普通账号,管理后台入口不会自动注册。
|
||
CreateAdminUserInput:
|
||
type: object
|
||
required: [name, email, role]
|
||
properties:
|
||
name:
|
||
type: string
|
||
minLength: 1
|
||
description: 姓名会去除首尾空白,不能为空。
|
||
email:
|
||
type: string
|
||
format: email
|
||
maxLength: 254
|
||
description: 邮箱会去除首尾空白并转为小写。
|
||
role:
|
||
type: string
|
||
enum: [admin, user]
|
||
password:
|
||
type: string
|
||
writeOnly: true
|
||
description: 管理员必填,至少 12 个字符;普通用户忽略此字段,由服务端生成独立的 16 位随机初始密码。
|
||
group_ids:
|
||
type: [array, 'null']
|
||
maxItems: 1000
|
||
description: 直接加入的分组 UUID,重复值自动去重;未传、null 或空数组表示不加入真实分组。禁止根分组 UUID。
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
allOf:
|
||
- if:
|
||
properties:
|
||
role:
|
||
const: admin
|
||
then:
|
||
required: [password]
|
||
properties:
|
||
password:
|
||
minLength: 12
|
||
AdminUserCreationResult:
|
||
allOf:
|
||
- $ref: '#/components/schemas/EmailAuthUser'
|
||
- type: object
|
||
required: [initial_password]
|
||
properties:
|
||
initial_password:
|
||
type: string
|
||
readOnly: true
|
||
minLength: 12
|
||
description: 仅创建成功时返回。普通成员为服务端生成的 16 位随机密码;管理员为创建时提交的密码。客户端仅可在本次创建结果中临时展示,不得缓存或写入日志,关闭结果后清除。
|
||
AccountProfile:
|
||
type: object
|
||
required: [user, custom_avatar_url, synced_avatar_url, has_password, csrf_token]
|
||
properties:
|
||
user: {$ref: '#/components/schemas/EmailAuthUser'}
|
||
custom_avatar_url: {type: string, description: 用户上传的头像地址,为空时使用同步头像。}
|
||
synced_avatar_url: {type: string, description: OAuth 自动同步的头像地址,不被手动上传修改。}
|
||
has_password: {type: boolean}
|
||
csrf_token: {type: string}
|
||
AvatarUpdate:
|
||
type: object
|
||
required: [user, custom_avatar_url]
|
||
properties:
|
||
user: {$ref: '#/components/schemas/EmailAuthUser'}
|
||
custom_avatar_url: {type: string}
|
||
AdminListUser:
|
||
allOf:
|
||
- $ref: '#/components/schemas/EmailAuthUser'
|
||
- type: object
|
||
required: [supervised_groups]
|
||
properties:
|
||
supervised_groups:
|
||
type: array
|
||
description: 主管负责的直属分组,非主管返回空数组。
|
||
items:
|
||
type: object
|
||
required: [id, name]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
name: {type: string}
|
||
EmailAuthUser:
|
||
type: object
|
||
required:
|
||
- id
|
||
- name
|
||
- email
|
||
- role
|
||
- status
|
||
- joined_at
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
email:
|
||
type: string
|
||
format: email
|
||
maxLength: 254
|
||
description: 邮箱会去除首尾空白并转为小写。
|
||
role:
|
||
type: string
|
||
enum:
|
||
- admin
|
||
- user
|
||
status:
|
||
type: string
|
||
enum:
|
||
- active
|
||
- disabled
|
||
joined_at:
|
||
type: string
|
||
format: date-time
|
||
avatar_url:
|
||
type: string
|
||
description: 最终展示头像,优先自定义头像,否则使用 OAuth 同步头像;均为空时省略。
|
||
last_login_at:
|
||
type: string
|
||
format: date-time
|
||
AuditPage:
|
||
type: object
|
||
required: [items, total, page, page_size]
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/AuditRecord"
|
||
total:
|
||
type: integer
|
||
minimum: 0
|
||
description: 所有匹配记录的数量。
|
||
page:
|
||
type: integer
|
||
minimum: 1
|
||
description: 请求页码。
|
||
page_size:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 500
|
||
description: 每页条数。
|
||
AuditRecord:
|
||
type: object
|
||
required: [id, actor_type, actor_user_id, actor_name, actor_email, actor_avatar_url, action, category, target_type, target_id, request_params, source_ip, user_agent, result, error_message, occurred_at, request_id]
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: "审计 ID。"
|
||
format: uuid
|
||
actor_type:
|
||
type: string
|
||
description: "操作者类型;登录失败是尚未认证的 user。"
|
||
enum: [user, system]
|
||
actor_user_id:
|
||
type: [string, "null"]
|
||
description: "操作者 ID;未认证用户及已删除用户为空。"
|
||
format: uuid
|
||
actor_name:
|
||
type: string
|
||
description: "操作者名称快照,未认证登录尝试固定为未认证用户。"
|
||
actor_email:
|
||
type: [string, "null"]
|
||
description: "操作者邮箱快照。"
|
||
actor_avatar_url:
|
||
type: [string, "null"]
|
||
description: "操作者当前的头像地址;无关联用户或头像为空时为 null,客户端使用默认头像。"
|
||
action:
|
||
type: string
|
||
description: "操作标识;客户端应为未知标识保留原文回退。"
|
||
category:
|
||
type: string
|
||
description: "操作分类,兼容既有记录。"
|
||
target_type:
|
||
type: [string, "null"]
|
||
description: "目标资源类型。"
|
||
target_id:
|
||
type: [string, "null"]
|
||
description: "目标 UUID;无具体对象时为空。"
|
||
format: uuid
|
||
request_params:
|
||
type: object
|
||
description: "白名单参数快照,未知字段与凭证替换为 [REDACTED];不保存上传文件、正文及原始响应。"
|
||
additionalProperties: true
|
||
source_ip:
|
||
type: [string, "null"]
|
||
description: "HTTP 对端 IPv4 或 IPv6 地址,历史记录可为空。"
|
||
user_agent:
|
||
type: [string, "null"]
|
||
description: "最多 512 个字符的客户端标识。"
|
||
result:
|
||
type: string
|
||
description: "执行结果。"
|
||
enum: [success, failed]
|
||
error_message:
|
||
type: [string, "null"]
|
||
description: "仅保存标准 HTTP 状态说明,不保存上游或数据库错误原文。"
|
||
occurred_at:
|
||
type: string
|
||
description: "操作发生时间。"
|
||
format: date-time
|
||
request_id:
|
||
type: [string, "null"]
|
||
description: "服务端生成的请求关联标识,同一批量操作可关联多个目标;历史或独立业务事件为空。"
|
||
StatisticsCredits: &statisticsCredits
|
||
type: string
|
||
pattern: ^-?[0-9]+(\.[0-9]{1,6})?$
|
||
description: 扣费减退款后的积分净消费,十进制字符串;纯退款周期可为负值。
|
||
StatisticsFrom: &statisticsFrom
|
||
type: string
|
||
format: date-time
|
||
description: 查询窗口起点,包含。
|
||
StatisticsUntil: &statisticsUntil
|
||
type: string
|
||
format: date-time
|
||
description: 查询窗口终点,不包含;由服务端统一确定。
|
||
StatisticsModelsOverview:
|
||
type: object
|
||
description: 模型调用与积分通过事务内维护的小时汇总统计;完整小时读取汇总,滚动窗口边界和最近 30 分钟耗时读取明细。北京时间日界、用量明确判定与截尾平均规则保持一致。
|
||
required: [timezone, generated_at, last_24h, previous_24h, last_30m, message_distribution, days]
|
||
properties:
|
||
timezone: {type: string, const: Asia/Shanghai}
|
||
generated_at: {type: string, format: date-time}
|
||
message_distribution:
|
||
$ref: "#/components/schemas/StatisticsModelMessageDistribution"
|
||
last_24h:
|
||
type: object
|
||
description: 按完成时间统计 [generated_at - 24 小时, generated_at) 内的非运行中调用。
|
||
required: [model_calls, input_tokens, output_tokens]
|
||
properties:
|
||
model_calls: {type: integer, minimum: 0}
|
||
input_tokens: {type: integer, minimum: 0}
|
||
output_tokens: {type: integer, minimum: 0}
|
||
previous_24h:
|
||
type: object
|
||
description: 按完成时间统计 [generated_at - 48 小时, generated_at - 24 小时) 内的非运行中调用,用于与 last_24h 比较。
|
||
required: [model_calls, input_tokens, output_tokens]
|
||
properties:
|
||
model_calls: {type: integer, minimum: 0}
|
||
input_tokens: {type: integer, minimum: 0}
|
||
output_tokens: {type: integer, minimum: 0}
|
||
last_30m:
|
||
type: object
|
||
required: [tpm, rpm, cache_hit_rate, model_success_rate, avg_response_time, avg_first_token_time]
|
||
properties:
|
||
tpm: {type: number, minimum: 0, description: 近 30 分钟完成且用量明确的调用的输入和输出 Token 总量除以 30。}
|
||
rpm: {type: number, minimum: 0, description: 近 30 分钟完成调用数除以 30。}
|
||
cache_hit_rate: {type: [number, 'null'], minimum: 0, maximum: 100, description: 无完成调用时为 null。}
|
||
model_success_rate: {type: [number, 'null'], minimum: 0, maximum: 100, description: 无完成调用时为 null。}
|
||
avg_response_time: {type: [number, 'null'], minimum: 0, description: 最近 30 分钟完成的成功调用响应耗时,独立剔除最慢 5% 样本后的算术平均值,单位毫秒。剔除条数向下取整,不足 20 条时保留全部样本;相同耗时按条数截尾。优先使用记录的响应耗时,否则使用完成时间减开始时间;无样本时为 null。}
|
||
avg_first_token_time: {type: [number, 'null'], minimum: 0, description: 最近 30 分钟完成的成功流式调用中,已采集首字耗时的样本独立剔除最慢 5% 后的算术平均值,单位毫秒。剔除条数向下取整,不足 20 条时保留全部样本;相同耗时按条数截尾。历史和非流式调用不计入;无样本时为 null。}
|
||
days:
|
||
type: array
|
||
minItems: 90
|
||
maxItems: 90
|
||
description: 从 89 天前到今天的北京时间自然日,按日期升序;空白日期补零。Token 仅累计用量明确的调用,输入包含缓存输入。
|
||
items:
|
||
type: object
|
||
required: [date, model_calls, input_tokens, output_tokens, credits]
|
||
properties:
|
||
date: {type: string, format: date}
|
||
model_calls: {type: integer, minimum: 0}
|
||
input_tokens: {type: integer, minimum: 0}
|
||
output_tokens: {type: integer, minimum: 0}
|
||
credits: {type: string, description: 模型扣费与退款的净积分,可能为负值,按十进制字符串返回。}
|
||
StatisticsModelMessageDistribution:
|
||
type: object
|
||
required: [from, until, total_messages, models]
|
||
properties:
|
||
from: {type: string, format: date-time, description: generated_at 减去 24 小时,包含。}
|
||
until: {type: string, format: date-time, description: 与 generated_at 相同,不包含。}
|
||
total_messages: {type: integer, minimum: 0, description: 窗口内有效根会话的全部上报消息数,与 models 消息数合计相等;不等同于模型调用次数。}
|
||
models:
|
||
type: array
|
||
description: 按消息数降序、模型 UUID 升序,未知模型在相同数量中排最后;同名不同 UUID 的模型不合并。无消息时为空数组,total_messages 为零。
|
||
items:
|
||
type: object
|
||
required: [id, name, messages]
|
||
properties:
|
||
id: {type: [string, "null"], format: uuid}
|
||
name: {type: [string, "null"], description: 优先取非空展示名称,其次上游模型名称,缺失时为 null。}
|
||
messages: {type: integer, minimum: 1}
|
||
StatisticsSessionOverview:
|
||
type: object
|
||
required: [timezone, generated_at, total_sessions, new_sessions_24h, active_sessions_24h, total_messages, last_24h, days]
|
||
properties:
|
||
timezone: {type: string, const: Asia/Shanghai}
|
||
generated_at: {type: string, format: date-time}
|
||
total_sessions: {type: integer, minimum: 0, description: 当前有效根会话总量。}
|
||
new_sessions_24h: {type: integer, minimum: 0, description: 滚动 24 小时内创建的有效根会话数。}
|
||
active_sessions_24h: {type: integer, minimum: 0, description: 滚动 24 小时内有消息的去重有效根会话数,也是每会话消息数的样本量。}
|
||
total_messages: {type: integer, minimum: 0, description: 有效根会话全部历史上报消息数,不含未来消息。}
|
||
last_24h:
|
||
type: object
|
||
required: [from, until, messages, outcomes, duration_seconds, messages_per_session, models]
|
||
properties:
|
||
from: {type: string, format: date-time, description: generated_at 减去 24 小时,包含。}
|
||
until: {type: string, format: date-time, description: 与 generated_at 相同,不包含。}
|
||
messages: {type: integer, minimum: 0}
|
||
outcomes:
|
||
type: object
|
||
required: [complete, error, interrupted, max_turns, output_limit, unknown]
|
||
description: 各结果消息数,合计等于 messages;无数据时全部为零。
|
||
properties:
|
||
complete: {type: integer, minimum: 0}
|
||
error: {type: integer, minimum: 0}
|
||
interrupted: {type: integer, minimum: 0, description: 用户取消。}
|
||
max_turns: {type: integer, minimum: 0}
|
||
output_limit: {type: integer, minimum: 0}
|
||
unknown: {type: integer, minimum: 0}
|
||
duration_seconds:
|
||
type: object
|
||
required: [average, p10, p90]
|
||
description: 消息处理耗时,单位为秒,不排除异常或未知结果;无消息时三项均为 null。
|
||
properties:
|
||
average: {type: [number, "null"], minimum: 0}
|
||
p10: {type: [number, "null"], minimum: 0}
|
||
p90: {type: [number, "null"], minimum: 0}
|
||
messages_per_session:
|
||
type: object
|
||
required: [average, p10, p90]
|
||
description: 按窗口内消息数量对活跃会话等权统计,排除无消息会话;无活跃会话时三项均为 null。
|
||
properties:
|
||
average: {type: [number, "null"], minimum: 0}
|
||
p10: {type: [integer, "null"], minimum: 1}
|
||
p90: {type: [integer, "null"], minimum: 1}
|
||
models:
|
||
type: array
|
||
description: 各模型使用的消息数,合计等于 messages;同名模型按 UUID 区分,缺失模型统一归入未知项。无数据时为空数组。
|
||
items:
|
||
type: object
|
||
required: [id, name, messages]
|
||
properties:
|
||
id: {type: [string, "null"], format: uuid}
|
||
name: {type: [string, "null"]}
|
||
messages: {type: integer, minimum: 1}
|
||
days:
|
||
type: array
|
||
minItems: 90
|
||
maxItems: 90
|
||
items:
|
||
type: object
|
||
required: [date, new_sessions, active_sessions, messages]
|
||
properties:
|
||
date: {type: string, format: date}
|
||
new_sessions: {type: integer, minimum: 0}
|
||
active_sessions: {type: integer, minimum: 0}
|
||
messages: {type: integer, minimum: 0}
|
||
StatisticsMemberActivity:
|
||
type: object
|
||
required: [active_members]
|
||
properties:
|
||
active_members: {type: integer, minimum: 0, description: 窗口内有上报轮次的去重未删除成员数。}
|
||
StatisticsMembersOverview:
|
||
type: object
|
||
required: [total_members, last_7d, previous_7d, last_24h, previous_24h, timezone, generated_at, days, message_depth]
|
||
properties:
|
||
message_depth:
|
||
type: object
|
||
description: 最近 168 小时内按轮次开始时间统计,每个有效上报的顶层会话轮次计一条消息,排除占位、已删除或已清除会话。成员范围同 total_members。
|
||
required: [percentiles, top_members]
|
||
properties:
|
||
percentiles:
|
||
type: array
|
||
maxItems: 101
|
||
description: 按 P0 至 P100 顺序返回最近秩法的消息数,包含零消息成员;没有成员时为空数组。
|
||
items: {type: integer, minimum: 0}
|
||
top_members:
|
||
type: array
|
||
maxItems: 15
|
||
description: 仅含消息数大于零的成员,按消息数降序、同数按成员 ID 升序。
|
||
items:
|
||
type: object
|
||
required: [id, name, email, avatar_url, messages]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
name: {type: string}
|
||
email: {type: string}
|
||
avatar_url: {type: [string, "null"]}
|
||
messages: {type: integer, minimum: 1}
|
||
total_members: {type: integer, minimum: 0, description: 与成员管理一致的未删除成员总数,包含管理员及停用成员。}
|
||
last_7d:
|
||
$ref: "#/components/schemas/StatisticsMemberActivity"
|
||
description: "[generated_at - 168 小时, generated_at) 的活跃成员。"
|
||
previous_7d:
|
||
$ref: "#/components/schemas/StatisticsMemberActivity"
|
||
description: "[generated_at - 336 小时, generated_at - 168 小时) 的活跃成员。"
|
||
last_24h:
|
||
$ref: "#/components/schemas/StatisticsMemberActivity"
|
||
description: "[generated_at - 24 小时, generated_at) 的活跃成员。"
|
||
previous_24h:
|
||
$ref: "#/components/schemas/StatisticsMemberActivity"
|
||
description: "[generated_at - 48 小时, generated_at - 24 小时) 的活跃成员。"
|
||
timezone: {type: string, const: Asia/Shanghai}
|
||
generated_at: {type: string, format: date-time}
|
||
days:
|
||
type: array
|
||
minItems: 90
|
||
maxItems: 90
|
||
description: 从 89 天前到今天的北京时间自然日,按日期升序,缺失日期补零;今天仅统计至 generated_at。
|
||
items:
|
||
type: object
|
||
required: [date, new_members, active_members]
|
||
properties:
|
||
date: {type: string, format: date}
|
||
new_members: {type: integer, minimum: 0, description: 该日创建且当前未删除的成员数。}
|
||
active_members: {type: integer, minimum: 0, description: 当日有上报轮次的去重未删除成员数。}
|
||
StatisticsMemberAnalysis:
|
||
type: object
|
||
required: [timezone, generated_at, member, summary, created_resources, activity, recent_tasks]
|
||
properties:
|
||
timezone: {type: string, const: Asia/Shanghai}
|
||
generated_at: {type: string, format: date-time}
|
||
member:
|
||
type: object
|
||
required: [id, name, email, status, avatar_url, groups]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
name: {type: string}
|
||
email: {type: string}
|
||
status: {type: string, enum: [active, disabled]}
|
||
avatar_url: {type: [string, "null"], description: 优先自定义头像,其次第三方头像。}
|
||
groups:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required: [id, name]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
name: {type: string}
|
||
summary:
|
||
type: object
|
||
required: [from, until, tasks, conversations, credits]
|
||
properties:
|
||
from: {type: string, format: date-time, description: 29 天前的北京时间零点,包含。}
|
||
until: {type: string, format: date-time, description: 与 generated_at 相同,不包含。}
|
||
tasks: {type: integer, minimum: 0}
|
||
conversations: {type: integer, minimum: 0}
|
||
credits: {type: string, pattern: '^-?[0-9]+(\.[0-9]+)?$', description: 所有类别扣费减退款的净积分消耗。}
|
||
created_resources:
|
||
type: object
|
||
required: [models, knowledge_bases, skills, experts, connectors, rules]
|
||
properties:
|
||
models: {type: integer, minimum: 0}
|
||
knowledge_bases: {type: "null", description: 知识库服务尚未接入,不能将缺失数据解释为零。}
|
||
skills: {type: integer, minimum: 0}
|
||
experts: {type: integer, minimum: 0}
|
||
connectors: {type: integer, minimum: 0}
|
||
rules: {type: integer, minimum: 0}
|
||
activity:
|
||
type: object
|
||
required: [from, until, days]
|
||
properties:
|
||
from: {type: string, format: date}
|
||
until: {type: string, format: date}
|
||
days:
|
||
type: array
|
||
minItems: 365
|
||
maxItems: 366
|
||
items:
|
||
type: object
|
||
required: [date, conversations]
|
||
properties:
|
||
date: {type: string, format: date}
|
||
conversations: {type: integer, minimum: 0}
|
||
recent_tasks:
|
||
type: array
|
||
maxItems: 10
|
||
items:
|
||
type: object
|
||
required: [id, title, turn_count, started_at, last_active_at]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
title: {type: string}
|
||
turn_count: {type: [integer, "null"], minimum: 0}
|
||
started_at: {type: string, format: date-time}
|
||
last_active_at: {type: string, format: date-time}
|
||
StatisticsRealtime:
|
||
type: object
|
||
required:
|
||
- from
|
||
- until
|
||
- model_consumption
|
||
- p95_response_time
|
||
- model_success_rate
|
||
- model_calls
|
||
- tpm
|
||
- rpm
|
||
- input_tokens
|
||
- output_tokens
|
||
- total_users
|
||
- active_users
|
||
- active_tasks
|
||
- new_tasks
|
||
properties:
|
||
from: *statisticsFrom
|
||
until: *statisticsUntil
|
||
model_consumption: *statisticsCredits
|
||
p95_response_time:
|
||
type:
|
||
- number
|
||
- "null"
|
||
description: 窗口内完成的模型调用响应耗时 P95,单位毫秒;优先使用记录的耗时,否则使用完成时间减开始时间。无样本为 null。
|
||
model_success_rate:
|
||
type:
|
||
- number
|
||
- "null"
|
||
description: 窗口内成功调用 / 已结束调用 × 100;取消计入分母,无样本为 null。
|
||
model_calls:
|
||
type: integer
|
||
minimum: 0
|
||
description: 窗口内完成的模型调用总数。
|
||
tpm:
|
||
type: number
|
||
description: 窗口内完成且用量明确的调用的输入加输出 Token 总量 / 窗口分钟数。
|
||
rpm:
|
||
type: number
|
||
description: 窗口内完成调用总数 / 窗口分钟数。
|
||
input_tokens:
|
||
type: integer
|
||
minimum: 0
|
||
description: 窗口内完成且用量明确的调用的输入 Token,包含缓存输入。
|
||
output_tokens:
|
||
type: integer
|
||
minimum: 0
|
||
description: 窗口内完成且用量明确的调用的输出 Token。
|
||
total_users:
|
||
type: integer
|
||
minimum: 0
|
||
description: 当前系统未删除的用户总数,包含已停用用户及管理员,不受时间范围影响。
|
||
active_users:
|
||
type: integer
|
||
minimum: 0
|
||
description: 窗口内完成模型或 MCP 调用、有会话活动或发起仍在执行的计费调用的去重用户数;并非登录 DAU。
|
||
active_tasks:
|
||
type: integer
|
||
minimum: 0
|
||
description: 窗口内有网关活动的未删除、非占位顶层任务去重数;可能已结束,并非正在运行的任务数。
|
||
new_tasks:
|
||
type: integer
|
||
minimum: 0
|
||
description: 窗口内开始的未删除、非占位、已上报顶层任务数。
|
||
StatisticsResourceUsage:
|
||
type: object
|
||
required: [items, next_cursor, pagination, from, until, generated_at, data_freshness_seconds]
|
||
properties:
|
||
items:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/StatisticsResourceUsageRow'}
|
||
next_cursor: {type: string, nullable: true}
|
||
pagination: {type: string, enum: [cursor]}
|
||
from: {type: string, format: date-time}
|
||
until: {type: string, format: date-time}
|
||
generated_at: {type: string, format: date-time}
|
||
data_freshness_seconds: {type: number, minimum: 0, nullable: true}
|
||
StatisticsResourceUsageRow:
|
||
type: object
|
||
required: [user_id, user_name, user_email, user_avatar_url, kind, resource_id, resource_name, version, enabled_sessions, available_sessions, used_sessions, calls, failed, failure_rate, sort_key]
|
||
properties:
|
||
user_id: {type: string, format: uuid, description: 会话所属用户 ID。}
|
||
user_name: {type: string, description: 用户当前名称。}
|
||
user_email: {type: string, description: 用户当前邮箱。}
|
||
user_avatar_url: {type: [string, 'null'], description: 用户当前头像地址;为空时使用默认头像。}
|
||
kind: {type: string}
|
||
resource_id: {type: string}
|
||
resource_name: {type: string, description: 后台配置名称、最新非空上报名称或原始 ID;内置工具保留原始 ID。}
|
||
version: {type: string, nullable: true}
|
||
enabled_sessions: {type: integer, minimum: 0}
|
||
available_sessions: {type: integer, minimum: 0}
|
||
used_sessions: {type: integer, minimum: 0}
|
||
calls: {type: integer, minimum: 0}
|
||
failed: {type: integer, minimum: 0}
|
||
failure_rate: {type: number, minimum: 0, maximum: 100, nullable: true}
|
||
sort_key: {type: string, description: 资源类别、ID、版本及用户 ID 组成的稳定分页键。}
|
||
StatisticsClientDistribution:
|
||
type: object
|
||
required: [value, count]
|
||
properties:
|
||
value:
|
||
type: string
|
||
nullable: true
|
||
description: 原始分类值,客户端版本不附加前缀;null 表示未知。
|
||
count:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
description: 归入此分类的去重会话数。
|
||
StatisticsClientOverview:
|
||
type: object
|
||
required: [metric, total, distributions, from, until, generated_at, data_freshness_seconds]
|
||
properties:
|
||
metric: {type: string, enum: [sessions], description: 计数口径固定为筛选后的去重会话数。}
|
||
total: {type: integer, format: int64, minimum: 0, description: 匹配的会话总数,包含未知分类。}
|
||
distributions:
|
||
type: object
|
||
required: [client_type, platform, client_version]
|
||
properties:
|
||
client_type:
|
||
type: array
|
||
description: 按会话数降序排列的全部客户端类型。
|
||
items: {$ref: '#/components/schemas/StatisticsClientDistribution'}
|
||
platform:
|
||
type: array
|
||
description: 按会话数降序排列的全部平台,包含未知平台。
|
||
items: {$ref: '#/components/schemas/StatisticsClientDistribution'}
|
||
client_version:
|
||
type: array
|
||
description: 按会话数降序排列的全部客户端版本,每个会话采用匹配的最后一轮版本。
|
||
items: {$ref: '#/components/schemas/StatisticsClientDistribution'}
|
||
from: {type: string, format: date-time, description: 实际统计窗口起点,包含。}
|
||
until: {type: string, format: date-time, description: 实际统计窗口终点,不包含。}
|
||
generated_at: {type: string, format: date-time, description: 响应生成时间。}
|
||
data_freshness_seconds: {type: number, minimum: 0, nullable: true, description: 距最新匹配轮次接收时间的秒数;没有匹配数据时为 null。}
|
||
StatisticsConversations:
|
||
type: object
|
||
required: [items, has_next, page, page_size]
|
||
properties:
|
||
items:
|
||
type: array
|
||
description: 当前页的对话轮次;没有数据时返回空数组。
|
||
items:
|
||
$ref: "#/components/schemas/StatisticsConversation"
|
||
has_next: {type: boolean, description: 每页多查一条判断是否还有下一页,不执行总数查询。}
|
||
page: {type: integer, minimum: 1, description: 请求页码;越界时 items 为空数组。}
|
||
page_size: {type: integer, minimum: 1, maximum: 500, description: 每页条数。}
|
||
StatisticsConversation:
|
||
type: object
|
||
required: [session_id, turn_index, task_title, user_id, user_name, user_email, user_avatar_url, started_at, ended_at, duration_seconds, input_text, input_text_truncated, input_kind, input_tokens, output_tokens, outcome, error_code, is_completed]
|
||
properties:
|
||
session_id: {type: string, format: uuid, description: 所属根会话 ID,即任务历史的任务 ID;与 turn_index 联合标识一个轮次。}
|
||
turn_index: {type: integer, minimum: 1, description: 客户端上报的轮次编号。}
|
||
task_title: {type: string, description: 所属任务当前标题,与任务历史一致。}
|
||
user_id: {type: string, format: uuid, description: 所属用户 ID。}
|
||
user_name: {type: string, description: 所属用户当前姓名。}
|
||
user_email: {type: string, description: 所属用户当前邮箱。}
|
||
user_avatar_url: {type: [string, 'null'], description: 所属用户当前头像地址;为空时使用默认头像。}
|
||
started_at: {type: string, format: date-time, description: 轮次开始时间,筛选和排序使用此时间。}
|
||
ended_at: {type: string, format: date-time, description: 轮次结束时间;此接口仅展示已结束且完成上报的轮次。}
|
||
duration_seconds: {type: number, minimum: 0, description: ended_at 减 started_at 的秒数,保留原始精度,前端按整秒显示。}
|
||
input_text: {type: [string, 'null'], description: 已上报的用户正文;未采集或无文本输入时为 null,不生成示例正文。}
|
||
input_text_truncated: {type: boolean, description: 正文是否已经被客户端截断。}
|
||
input_kind: {type: string, description: 客户端上报的输入类型。}
|
||
input_tokens: {type: [integer, 'null'], minimum: 0, description: 本轮客户端上报的输入 Token 数;未采集时为 null,不合并模型网关或子代理用量。}
|
||
output_tokens: {type: [integer, 'null'], minimum: 0, description: 本轮客户端上报的输出 Token 数;未采集时为 null,K/M/B 由前端格式化。}
|
||
outcome:
|
||
type: string
|
||
enum: [complete, interrupted, error, max_turns, output_limit, unknown]
|
||
description: 本轮原始结束原因;不表示整个任务是否结束。
|
||
error_code: {type: [string, 'null'], description: 已上报的错误码,无错误码时为 null。}
|
||
is_completed: {type: [boolean, 'null'], description: complete 为 true;unknown 为 null;其他结束原因为 false。只表示本轮是否正常完成。}
|
||
StatisticsHistory:
|
||
type: object
|
||
required:
|
||
- items
|
||
- has_next
|
||
- page
|
||
- page_size
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required:
|
||
- id
|
||
- title
|
||
- user_id
|
||
- user_name
|
||
- user_email
|
||
- user_avatar_url
|
||
- started_at
|
||
- last_active_at
|
||
- turn_count
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
title:
|
||
type: string
|
||
description: 会话标题。
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
description: 所属用户 ID。
|
||
user_name:
|
||
type: string
|
||
description: 所属用户当前姓名。
|
||
user_email:
|
||
type: string
|
||
description: 所属用户当前邮箱。
|
||
user_avatar_url:
|
||
type: [string, 'null']
|
||
description: 所属用户当前头像地址;为空时使用默认头像。
|
||
started_at:
|
||
type: string
|
||
format: date-time
|
||
description: 会话开始时间。
|
||
last_active_at:
|
||
type: string
|
||
format: date-time
|
||
description: 最近活动时间。
|
||
turn_count:
|
||
type: [integer, 'null']
|
||
minimum: 0
|
||
description: 已维护的累计轮次数;存量后台校准期间为 null,不在列表请求中执行计数查询。
|
||
has_next:
|
||
type: boolean
|
||
description: 每页多查一条判断是否还有下一页,不执行总数查询。
|
||
page:
|
||
type: integer
|
||
minimum: 1
|
||
description: 请求页码;越界时 items 为空数组。
|
||
page_size:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 500
|
||
CreateMemberGroupInput:
|
||
allOf:
|
||
- $ref: "#/components/schemas/MemberGroupInput"
|
||
- type: object
|
||
required: [name]
|
||
MemberGroupMembersInput:
|
||
type: object
|
||
required: [member_ids]
|
||
properties:
|
||
member_ids:
|
||
type: array
|
||
maxItems: 10000
|
||
description: 完整的直接成员 ID 列表,空数组表示清空,重复 ID 自动去重;用户须存在且未删除。
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
MemberGroupMoveInput:
|
||
type: object
|
||
required: [target_id]
|
||
description: group_ids 与 members 必须且只能有一个非空数组,分别最多 100 个分组和 1000 条成员来源关系。
|
||
properties:
|
||
target_id:
|
||
type: string
|
||
format: uuid
|
||
description: 目标分组 UUID;全零 UUID 表示虚拟根。
|
||
group_ids:
|
||
type: array
|
||
maxItems: 100
|
||
uniqueItems: true
|
||
description: 需移动的分组 ID;不能包含虚拟根或同时包含父子分组。
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
members:
|
||
type: array
|
||
maxItems: 1000
|
||
description: 需移动的成员及其来源分组;同一成员允许从不同来源分组移走。
|
||
items:
|
||
type: object
|
||
required: [id]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
source_group_id:
|
||
type: string
|
||
format: uuid
|
||
description: 树中拖动时指定来源分组;省略表示从成员列表拖动,仅追加目标分组关系。
|
||
MemberGroupInput:
|
||
type: object
|
||
minProperties: 1
|
||
anyOf:
|
||
- required: [name]
|
||
- required: [parent_id]
|
||
properties:
|
||
name:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 100
|
||
description: 去除首尾空白后不能为空;同级名称不区分大小写且不能重复。
|
||
parent_id:
|
||
type: [string, "null"]
|
||
format: uuid
|
||
description: 新上级分组 ID,必须是有效分组;全零 UUID 或 null 表示虚拟根节点,更新时省略则保留原值。
|
||
MemberGroupsResponse:
|
||
type: object
|
||
required: [groups]
|
||
properties:
|
||
groups:
|
||
type: array
|
||
description: 首项为全零 UUID 的虚拟根节点,其余未删除分组按创建时间和 ID 排序。
|
||
items:
|
||
$ref: "#/components/schemas/MemberGroup"
|
||
MemberGroup:
|
||
type: object
|
||
required: [id, parent_id, name, member_ids, supervisor_ids, actions, allow_add_members]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: 分组唯一标识;虚拟根节点固定为 00000000-0000-0000-0000-000000000000。
|
||
parent_id:
|
||
type: [string, "null"]
|
||
format: uuid
|
||
description: 上级分组 ID;仅虚拟根节点为 null,其他顶层分组指向根节点的全零 UUID。
|
||
name:
|
||
type: string
|
||
description: 分组显示名称。
|
||
member_ids:
|
||
type: array
|
||
description: 未删除用户的直接分组关系,不含子分组成员;虚拟根节点列出未直接加入其他有效分组的用户,新用户自动归属该节点。
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
supervisor_ids:
|
||
type: array
|
||
description: 当前直属成员中的主管 ID。没有主管或为虚拟根节点时返回空数组。
|
||
items: {type: string, format: uuid}
|
||
actions:
|
||
type: array
|
||
description: 后端允许在该分组上执行的管理动作;根节点仅允许新增子组。
|
||
items:
|
||
type: string
|
||
enum: [add-subgroup, rename, adjust-members, set-supervisors, move, delete]
|
||
allow_add_members:
|
||
type: boolean
|
||
description: 是否允许从成员列表向本分组拖动并追加成员关系;虚拟根节点为 false。
|
||
CreditAmount:
|
||
type: string
|
||
pattern: ^-?\d+(\.\d{1,6})?$
|
||
description: 十进制定点积分,最多六位小数。
|
||
BillingPrice:
|
||
type: object
|
||
properties:
|
||
input:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
cached:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
output:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
multiplier:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
tool:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
BillingPolicy:
|
||
type: object
|
||
properties:
|
||
environment:
|
||
$ref: '#/components/schemas/EnvironmentBillingConfig'
|
||
root_credits:
|
||
$ref: "#/components/schemas/CreditAmount"
|
||
revision:
|
||
type: integer
|
||
enabled:
|
||
type: boolean
|
||
charging_mode:
|
||
description: local 为本地扣费;remote 为百智云扣费,仅具有有效百智云登录身份的用户可访问系统资源,用户自建资源仍遵循原授权。
|
||
enum:
|
||
- local
|
||
- remote
|
||
quota_refresh_cycle:
|
||
enum:
|
||
- daily
|
||
- weekly
|
||
- monthly
|
||
pending_cycle:
|
||
enum:
|
||
- daily
|
||
- weekly
|
||
- monthly
|
||
cycle_effective_at:
|
||
type: string
|
||
format: date-time
|
||
description: 新刷新规则的下一自然边界;保存时不重置当期余额,切换时才发放新周期额度。
|
||
cycle_anchor:
|
||
type: string
|
||
format: date-time
|
||
cycle_transition_start:
|
||
type: string
|
||
format: date-time
|
||
description: 待切换期间保留的当前账户起点,直到 cycle_effective_at 均沿用此账户。
|
||
input_credits_per_million_tokens:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
cached_input_credits_per_million_tokens:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
output_credits_per_million_tokens:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
required:
|
||
- revision
|
||
- enabled
|
||
- charging_mode
|
||
- quota_refresh_cycle
|
||
BillingWalletInput:
|
||
type: object
|
||
additionalProperties: false
|
||
required:
|
||
- revision
|
||
- base_url
|
||
- app_id
|
||
properties:
|
||
revision:
|
||
type: integer
|
||
description: 当前计费策略修订号;保存连接配置会递增该修订号。
|
||
base_url:
|
||
type: string
|
||
format: uri
|
||
description: 百智云 HTTPS 服务根地址,可包含端口,不含路径、查询参数、片段或用户信息。公有云填写 https://baizhi.cloud 或 https://baizhiyun.vip,私有化填写同时提供用户和钱包接口的统一网关地址。
|
||
example: https://baizhi.cloud
|
||
app_id:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 999
|
||
description: 所填服务对应的百智云应用 ID。
|
||
certificate:
|
||
type: string
|
||
maxLength: 65536
|
||
writeOnly: true
|
||
description: 客户端证书 PEM 内容,首次配置必填,省略或空字符串保留已保存值。
|
||
private_key:
|
||
type: string
|
||
maxLength: 65536
|
||
writeOnly: true
|
||
description: PKCS#8 ECDSA 私钥 PEM 内容,首次配置必填,省略或空字符串保留已保存值;不回显、不写入审计明文。
|
||
ca_certificate:
|
||
type: string
|
||
maxLength: 65536
|
||
writeOnly: true
|
||
description: 服务端根 CA 证书 PEM 内容,首次配置必填,省略或空字符串保留已保存值。
|
||
BillingWalletInfo:
|
||
type: object
|
||
description: 仅返回连接元信息;configured 表示本地证书校验通过,不代表远程网络连通或账户授权成功。
|
||
properties:
|
||
configured:
|
||
type: boolean
|
||
credentials_configured:
|
||
type: boolean
|
||
description: 是否已有完整证书和私钥;为 true 时更新配置可以省略对应文件。
|
||
base_url:
|
||
type: string
|
||
format: uri
|
||
app_id:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 999
|
||
certificate_expires_at:
|
||
type: string
|
||
format: date-time
|
||
source:
|
||
type: string
|
||
enum: [admin, environment]
|
||
description: 当前使用后台保存的配置或部署环境配置;后台配置优先。
|
||
error:
|
||
type: string
|
||
description: 配置无效或证书过期时的提示,不包含凭证原文。
|
||
required:
|
||
- configured
|
||
- credentials_configured
|
||
CreditAccount:
|
||
type: object
|
||
properties:
|
||
version:
|
||
type: string
|
||
description: 当前账户的版本,随账本变更更新;用于管理员调整时检查并发及重复提交,历史账户条目可省略。
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
group_id:
|
||
type: string
|
||
description: 计费分组 UUID;未指定归属时为空字符串。
|
||
period_start_at:
|
||
type: string
|
||
format: date-time
|
||
period_end_at:
|
||
type: string
|
||
format: date-time
|
||
balance:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
frozen:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
description: 兼容字段,迁移后为零。
|
||
available:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
quota:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
required:
|
||
- id
|
||
- user_id
|
||
- balance
|
||
- frozen
|
||
- available
|
||
- quota
|
||
- period_start_at
|
||
- period_end_at
|
||
CreditEntry:
|
||
type: object
|
||
properties:
|
||
user_avatar_url:
|
||
type: [string, 'null']
|
||
description: 管理员流水列表返回用户当前头像;为空时使用默认头像。
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
account_id:
|
||
type: string
|
||
format: uuid
|
||
transaction_id:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: uuid
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
user_name:
|
||
type: string
|
||
user_email:
|
||
type: string
|
||
item_name:
|
||
type: string
|
||
category:
|
||
enum:
|
||
- model
|
||
- tool
|
||
- image
|
||
- video
|
||
- environment
|
||
- other
|
||
entry_type:
|
||
enum:
|
||
- grant
|
||
- charge
|
||
- refund
|
||
- adjustment
|
||
- reset
|
||
credit_delta:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
balance_after:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
mode:
|
||
enum:
|
||
- local
|
||
- remote
|
||
sequence:
|
||
type: string
|
||
occurred_at:
|
||
type: string
|
||
format: date-time
|
||
metadata:
|
||
type: object
|
||
BillingUsage:
|
||
type: object
|
||
properties:
|
||
known:
|
||
type: boolean
|
||
stream:
|
||
type: boolean
|
||
description: 是否为流式调用;历史记录可能缺失。
|
||
result:
|
||
enum:
|
||
- succeeded
|
||
- failed
|
||
- cancelled
|
||
request_id:
|
||
type: string
|
||
error_code:
|
||
type: string
|
||
terminal_event:
|
||
type: string
|
||
description: 代理观察到的流终止事件或非流式响应状态。
|
||
initial_error_code:
|
||
type: string
|
||
description: 自动对账前的原始异常原因。
|
||
reconciled:
|
||
type: boolean
|
||
description: 是否已通过上游查询自动补全用量。
|
||
input_tokens:
|
||
type: integer
|
||
minimum: 0
|
||
cached_input_tokens:
|
||
type: integer
|
||
minimum: 0
|
||
output_tokens:
|
||
type: integer
|
||
minimum: 0
|
||
environment_id: {type: string, format: uuid}
|
||
period_id: {type: string, format: uuid}
|
||
from: {type: string, format: date-time}
|
||
until: {type: string, format: date-time}
|
||
duration_seconds: {type: integer, format: int64, minimum: 0}
|
||
cpu_millis: {type: integer, format: int64, minimum: 1}
|
||
memory_bytes: {type: integer, format: int64, minimum: 1}
|
||
required:
|
||
- result
|
||
BillingTransaction:
|
||
type: object
|
||
properties:
|
||
user_avatar_url:
|
||
type: [string, 'null']
|
||
description: 管理员待处理列表返回用户当前头像;为空时使用默认头像。
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
user_name:
|
||
type: string
|
||
user_email:
|
||
type: string
|
||
item_name:
|
||
type: string
|
||
account_id:
|
||
type: string
|
||
format: uuid
|
||
session_id:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: uuid
|
||
category:
|
||
enum:
|
||
- model
|
||
- tool
|
||
- image
|
||
- video
|
||
- environment
|
||
mode:
|
||
enum:
|
||
- local
|
||
- remote
|
||
status:
|
||
enum:
|
||
- created
|
||
- reserved
|
||
- running
|
||
- settling
|
||
- settled
|
||
- released
|
||
- rejected
|
||
- unknown
|
||
reserve:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
amount:
|
||
anyOf:
|
||
- $ref: '#/components/schemas/CreditAmount'
|
||
- type: 'null'
|
||
raw_amount:
|
||
anyOf:
|
||
- $ref: '#/components/schemas/CreditAmount'
|
||
- type: 'null'
|
||
pricing:
|
||
anyOf:
|
||
- $ref: '#/components/schemas/BillingPrice'
|
||
- $ref: agent.yaml#/components/schemas/EnvironmentBillingPricing
|
||
usage:
|
||
$ref: '#/components/schemas/BillingUsage'
|
||
error_code:
|
||
type: string
|
||
attempts:
|
||
type: integer
|
||
started_at:
|
||
type: string
|
||
format: date-time
|
||
completed_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
entries:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/CreditEntry'
|
||
wallet_records:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
biz_id:
|
||
type: string
|
||
status:
|
||
type: string
|
||
external_user_id:
|
||
type: string
|
||
base_url:
|
||
type: string
|
||
format: uri
|
||
app_id:
|
||
type: integer
|
||
frozen_amount_quota:
|
||
type: string
|
||
actual_amount_quota:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
trace_id:
|
||
type: string
|
||
error_code:
|
||
type: string
|
||
ErrorResponse:
|
||
type: object
|
||
required: [error]
|
||
properties:
|
||
error:
|
||
$ref: "#/components/schemas/Error"
|
||
Error:
|
||
type: object
|
||
required: [code, message]
|
||
properties:
|
||
code:
|
||
type: string
|
||
description: 供调用方识别错误类别的稳定代码。
|
||
examples: [model_error]
|
||
message:
|
||
type: string
|
||
description: 服务端按 Accept-Language 返回的本地化错误说明,末尾附 [trace_id] 链路编号,与服务日志 trace_id 对应;可直接展示,支持 zh-CN、en-US,缺省为 zh-CN。
|
||
references:
|
||
description: 原有业务恢复字段,仅按接口契约读取。
|
||
ModelsResponse:
|
||
type: object
|
||
required: [models]
|
||
properties:
|
||
next_cursor:
|
||
type: string
|
||
description: 后续页游标;无后续页或未启用分页时为空字符串。
|
||
models:
|
||
type: array
|
||
description: 分页时按 ID 升序;未启用分页时按创建时间倒序。
|
||
items:
|
||
$ref: "#/components/schemas/Model"
|
||
SystemProxy:
|
||
type: object
|
||
required: [name, url]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
name: {type: string}
|
||
url: {type: string, pattern: "^(http|https|socks5)://"}
|
||
username: {type: string}
|
||
password: {type: string, writeOnly: true}
|
||
MCPNetworkValue:
|
||
type: object
|
||
required: [blocked_cidrs]
|
||
properties:
|
||
blocked_cidrs:
|
||
type: array
|
||
items:
|
||
type: string
|
||
examples: ["10.0.0.0/8", "fd00::/8", "192.168.1.1/32"]
|
||
MCPNetworkSetting:
|
||
type: object
|
||
required: [key, value, schema_version, updated_by_user_id, updated_at]
|
||
properties:
|
||
key: {type: string, const: mcp}
|
||
value:
|
||
$ref: "#/components/schemas/MCPNetworkValue"
|
||
schema_version: {type: integer}
|
||
updated_by_user_id: {type: string, format: uuid}
|
||
updated_at: {type: string, format: date-time}
|
||
ProxySetting:
|
||
type: object
|
||
properties:
|
||
key: {type: string, const: proxies}
|
||
schema_version: {type: integer}
|
||
value:
|
||
type: object
|
||
properties:
|
||
proxies:
|
||
type: array
|
||
items:
|
||
$ref: "#/components/schemas/SystemProxy"
|
||
Model:
|
||
type: object
|
||
required:
|
||
- id
|
||
- ownership_type
|
||
- user
|
||
- model_id
|
||
- display_name
|
||
- protocol
|
||
- kind
|
||
- provider
|
||
- base_url
|
||
- api_key_configured
|
||
- authorization
|
||
- enabled
|
||
- created_at
|
||
- updated_at
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: MonkeyAI 内部模型 ID,也是 Agent 调用时使用的 model 值。
|
||
ownership_type:
|
||
type: string
|
||
enum: [system, user]
|
||
description: system 表示管理员配置的系统模型,user 表示用户自带模型。
|
||
user:
|
||
$ref: '#/components/schemas/UserSummary'
|
||
readOnly: true
|
||
description: 资源所有者的基本信息;系统资源返回创建者,分享不改变归属。
|
||
model_id:
|
||
type: string
|
||
description: 上游服务使用的模型标识。
|
||
display_name:
|
||
type: string
|
||
description: 管理后台和 Agent 展示的模型名称。
|
||
protocol:
|
||
$ref: "#/components/schemas/ModelProtocol"
|
||
kind:
|
||
$ref: "#/components/schemas/ModelKind"
|
||
provider:
|
||
$ref: "#/components/schemas/ModelProvider"
|
||
image_config:
|
||
$ref: "#/components/schemas/ImageConfig"
|
||
image_pricing:
|
||
$ref: "#/components/schemas/ImagePricing"
|
||
embedding_config:
|
||
$ref: "#/components/schemas/EmbeddingConfig"
|
||
base_url:
|
||
type: string
|
||
format: uri
|
||
description: 上游模型服务的 HTTP(S) 基础地址。
|
||
proxy_id:
|
||
type: string
|
||
description: 系统代理资源 ID;空字符串表示直连。
|
||
api_key_configured:
|
||
type: boolean
|
||
description: 是否已配置上游 API Key;响应不会返回密钥原文。
|
||
advanced_config:
|
||
$ref: "#/components/schemas/AdvancedConfig"
|
||
credit_multiplier:
|
||
type: number
|
||
exclusiveMinimum: 0
|
||
description: 本模型消耗积分时使用的倍率。
|
||
tags:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ResourceTag'}
|
||
authorization:
|
||
$ref: "#/components/schemas/Authorization"
|
||
enabled:
|
||
type: boolean
|
||
description: 模型是否允许被调用。
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
description: 模型创建时间。
|
||
updated_at:
|
||
type: string
|
||
format: date-time
|
||
description: 模型最后更新时间。
|
||
ModelProtocol:
|
||
type: string
|
||
enum: [openai_chat_completions, openai_responses, anthropic, image_generation, video_generation, openai_embeddings]
|
||
description: MonkeyAI 与上游服务通信时使用的协议。
|
||
ModelKind:
|
||
type: string
|
||
enum: [text, image, video, embedding]
|
||
description: 模型对外提供的能力;省略时兼容为 text。
|
||
ModelProvider:
|
||
type: string
|
||
enum: [passthrough, openai_images, openai_responses_image, volcengine, xai, agnes]
|
||
description: 上游调用路径;text 和 embedding 模型只允许 passthrough。
|
||
EmbeddingConfig:
|
||
type: object
|
||
required: [dimension]
|
||
properties:
|
||
dimension:
|
||
type: integer
|
||
minimum: 1
|
||
maximum: 16000
|
||
description: 服务端保存时自动探测的向量维度,1–16000,用于知识库 pgvector 列类型校验;客户端不可配置。
|
||
EmbeddingProbeResult:
|
||
type: object
|
||
required: [dimension, configured_dimension, dimension_matches, vector_preview, prompt_tokens, total_tokens]
|
||
properties:
|
||
dimension: {type: integer, minimum: 1, maximum: 16000, description: 本次 embedding 响应返回的实际向量维度。}
|
||
configured_dimension: {type: integer, minimum: 1, maximum: 16000, description: 模型保存时探测并记录的向量维度。}
|
||
dimension_matches: {type: boolean, description: 实际维度是否与已保存配置一致。}
|
||
vector_preview:
|
||
type: array
|
||
maxItems: 8
|
||
items: {type: number}
|
||
description: 返回向量的前 8 个元素,便于确认响应内容有效。
|
||
prompt_tokens: {type: integer, minimum: 0, description: 上游返回的输入 Token 数;未提供时为 0。}
|
||
total_tokens: {type: integer, minimum: 0, description: 上游返回的总 Token 数;未提供时为 0。}
|
||
ImageQuality:
|
||
type: string
|
||
enum: [1K, 2K, 4K]
|
||
description: 平台统一的生图画质档位;具体像素由供应商适配器映射。
|
||
ImageConfig:
|
||
type: object
|
||
required: [qualities, aspect_ratios, default_quality, default_aspect_ratio]
|
||
properties:
|
||
qualities:
|
||
type: array
|
||
minItems: 1
|
||
uniqueItems: true
|
||
items: {$ref: '#/components/schemas/ImageQuality'}
|
||
aspect_ratios:
|
||
type: array
|
||
minItems: 1
|
||
uniqueItems: true
|
||
items: {type: string, pattern: '^[1-9][0-9]*:[1-9][0-9]*$'}
|
||
default_quality: {$ref: '#/components/schemas/ImageQuality'}
|
||
default_aspect_ratio: {type: string}
|
||
ImageMultiplier:
|
||
type: object
|
||
required: [name, multiplier]
|
||
properties:
|
||
name: {$ref: '#/components/schemas/ImageQuality'}
|
||
multiplier:
|
||
type: string
|
||
pattern: '^[0-9]+(\.[0-9]{1,6})?$'
|
||
description: 大于 0 的十进制倍率,最多 6 位小数。
|
||
ImageRate:
|
||
type: object
|
||
required: [quality, credits_per_image]
|
||
properties:
|
||
quality: {$ref: '#/components/schemas/ImageQuality'}
|
||
credits_per_image:
|
||
type: string
|
||
pattern: '^[0-9]+(\.[0-9]{1,6})?$'
|
||
description: 该画质每张图的最终积分价,允许 0,最多六位小数。
|
||
ImagePricing:
|
||
type: object
|
||
description: 返回按画质配置的单张积分价格。写入兼容旧版基础价和倍率,但不可与 rates 混用;旧配置按原定点计算规则换算后返回,不重写历史账单。
|
||
oneOf:
|
||
- required: [rates]
|
||
not:
|
||
anyOf:
|
||
- required: [base_credits_per_image]
|
||
- required: [quality_multipliers]
|
||
- required: [base_credits_per_image]
|
||
not: {required: [rates]}
|
||
properties:
|
||
rates:
|
||
type: array
|
||
minItems: 1
|
||
maxItems: 3
|
||
description: 每个已开放画质必须恰好配置一次。
|
||
items: {$ref: '#/components/schemas/ImageRate'}
|
||
base_credits_per_image: {type: string, deprecated: true, pattern: '^[0-9]+(\.[0-9]{1,6})?$'}
|
||
quality_multipliers:
|
||
type: array
|
||
deprecated: true
|
||
items: {$ref: '#/components/schemas/ImageMultiplier'}
|
||
AdvancedConfig:
|
||
type: object
|
||
required: [context_window_tokens, max_output_tokens, supports_vision]
|
||
properties:
|
||
context_window_tokens:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
description: 文本模型必须大于 0;生图模型返回 0。
|
||
max_output_tokens:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
description: 文本模型必须大于 0;生图模型返回 0。
|
||
supports_vision:
|
||
type: boolean
|
||
description: 模型是否支持图像输入。
|
||
supports_reasoning:
|
||
type: boolean
|
||
default: false
|
||
description: 模型是否支持推理能力;旧模型省略时视为 false。
|
||
Authorization:
|
||
type: object
|
||
description: 可使用该模型的用户和分组。全零 UUID 根分组表示全员授权(包括后续新增用户),服务端入库时转为 all_users,管理端回包统一以 group_ids 中的根 UUID 表示。兼容输入 all_users=true,此时忽略其他授权 ID。
|
||
required: [user_ids, group_ids]
|
||
properties:
|
||
all_users:
|
||
type: boolean
|
||
default: false
|
||
description: 兼容写入全员授权的旧字段;管理端回包固定为 false,统一通过 group_ids 中的根 UUID 表示。
|
||
user_ids:
|
||
type: array
|
||
description: 获得模型访问权的用户 UUID。
|
||
uniqueItems: true
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
group_ids:
|
||
type: array
|
||
description: 获得模型访问权的分组 UUID;全零 UUID 表示全员。
|
||
uniqueItems: true
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
ModelInput:
|
||
type: object
|
||
required:
|
||
- model_id
|
||
- display_name
|
||
- protocol
|
||
- base_url
|
||
- authorization
|
||
properties:
|
||
model_id:
|
||
type: string
|
||
minLength: 1
|
||
description: 上游服务使用的模型标识。
|
||
display_name:
|
||
type: string
|
||
minLength: 1
|
||
description: 模型展示名称。
|
||
protocol:
|
||
$ref: "#/components/schemas/ModelProtocol"
|
||
kind:
|
||
$ref: "#/components/schemas/ModelKind"
|
||
provider:
|
||
$ref: "#/components/schemas/ModelProvider"
|
||
provider_options:
|
||
type: object
|
||
description: 非敏感路由参数,不包含上游密钥或画质比例映射。
|
||
image_config:
|
||
$ref: "#/components/schemas/ImageConfig"
|
||
image_pricing:
|
||
$ref: "#/components/schemas/ImagePricing"
|
||
base_url:
|
||
type: string
|
||
format: uri
|
||
pattern: "^https?://"
|
||
description: 上游模型服务的 HTTP(S) 基础地址。
|
||
proxy_id:
|
||
type: string
|
||
description: 系统代理资源 ID;空字符串表示直连。
|
||
api_key:
|
||
type: string
|
||
description: 上游 API Key;更新时传空字符串可保留原密钥。
|
||
advanced_config:
|
||
$ref: "#/components/schemas/AdvancedConfig"
|
||
credit_multiplier:
|
||
type: number
|
||
exclusiveMinimum: 0
|
||
description: 积分消耗倍率。
|
||
tag_ids:
|
||
type: array
|
||
items: {type: string, format: uuid}
|
||
authorization:
|
||
$ref: "#/components/schemas/Authorization"
|
||
CreateModelInput:
|
||
allOf:
|
||
- $ref: "#/components/schemas/ModelInput"
|
||
- type: object
|
||
required: [api_key]
|
||
properties:
|
||
api_key:
|
||
type: string
|
||
minLength: 1
|
||
description: 上游 API Key,创建时不能为空。
|
||
SetModelEnabledInput:
|
||
type: object
|
||
required: [enabled]
|
||
properties:
|
||
enabled:
|
||
type: boolean
|
||
description: true 为启用模型,false 为停用模型。
|
||
AuthorizationSubjects:
|
||
type: object
|
||
required: [groups, users]
|
||
properties:
|
||
groups:
|
||
type: array
|
||
description: 包含全零 UUID 的虚拟根节点及全部可授权分组。
|
||
items:
|
||
$ref: "#/components/schemas/GroupSubject"
|
||
users:
|
||
type: array
|
||
description: 可授权的活跃用户。
|
||
items:
|
||
$ref: "#/components/schemas/UserSubject"
|
||
GroupSubject:
|
||
type: object
|
||
required: [id, name]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: 分组 ID。
|
||
parent_id:
|
||
type: string
|
||
format: uuid
|
||
description: 父分组 ID;仅虚拟根分组不返回该字段,其他顶层分组指向根 UUID。
|
||
name:
|
||
type: string
|
||
description: 分组名称。
|
||
UserSubject:
|
||
type: object
|
||
required: [id, name, email, group_id]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: 用户 ID。
|
||
name:
|
||
type: string
|
||
description: 用户显示名称。
|
||
email:
|
||
type: string
|
||
format: email
|
||
description: 用户邮箱。
|
||
avatar_url:
|
||
type: string
|
||
description: 当前用户头像地址;未配置时省略。
|
||
group_id:
|
||
type: string
|
||
format: uuid
|
||
description: 授权选择器展示的用户所属分组;未加入其他分组时为根 UUID,多组用户取创建时间最早的分组。
|
||
APIKeysResponse:
|
||
type: object
|
||
required: [api_keys]
|
||
properties:
|
||
api_keys:
|
||
type: array
|
||
description: 调用密钥元数据,不包含可用于鉴权的密钥原文。
|
||
items:
|
||
$ref: "#/components/schemas/APIKey"
|
||
APIKey:
|
||
type: object
|
||
required:
|
||
- id
|
||
- user_id
|
||
- name
|
||
- key_prefix
|
||
- scopes
|
||
- expires_at
|
||
- created_at
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
description: 调用密钥 ID。
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
description: 密钥所属用户 ID。
|
||
user_name:
|
||
type: string
|
||
description: 密钥所属用户的显示名称。
|
||
name:
|
||
type: string
|
||
description: 用户设置的密钥名称。
|
||
key_prefix:
|
||
type: string
|
||
description: 用于识别密钥的安全前缀,不可用于鉴权。
|
||
examples:
|
||
- mk_abcd1234
|
||
scopes:
|
||
type: array
|
||
description: 密钥具备的调用权限。
|
||
minItems: 1
|
||
uniqueItems: true
|
||
items:
|
||
type: string
|
||
enum:
|
||
- model:invoke
|
||
- mcp:invoke
|
||
expires_at:
|
||
type: string
|
||
format: date-time
|
||
description: 密钥过期时间。
|
||
last_used_at:
|
||
type: string
|
||
format: date-time
|
||
description: 最近一次成功使用时间;从未使用时不返回。
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
description: 密钥创建时间。
|
||
revoked_at:
|
||
type: string
|
||
format: date-time
|
||
description: 密钥撤销时间;尚未撤销时不返回。
|
||
UserSummary:
|
||
type: object
|
||
required: [id, name, email]
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
description: 用户名。
|
||
email:
|
||
type: string
|
||
format: email
|
||
ResourceGrant:
|
||
type: object
|
||
description: 每条授权只能选择用户或分组之一;全零 UUID 的虚拟根分组表示全员授权,服务端入库时转换为 all_users,管理端读取时转换回 group_id。兼容写入 all_users=true,但不能同时指定用户或分组。
|
||
properties:
|
||
id: {type: string, format: uuid, readOnly: true}
|
||
access_level:
|
||
type: string
|
||
enum: [read_only, read_write]
|
||
description: 知识库只读或读写权限;读写包含删除内容,不包含管理授权或删除整个库。旧请求省略时保留现有权限,新主体默认只读。
|
||
all_users:
|
||
type: boolean
|
||
default: false
|
||
description: 兼容旧请求的全员授权字段;管理端回包固定为 false,改由根分组 UUID 表示。
|
||
user_id:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: uuid
|
||
user:
|
||
readOnly: true
|
||
description: 用户授权的展示信息;分组、全员授权或用户已删除时为 null。停用用户仍返回信息,便于撤销授权。
|
||
anyOf:
|
||
- $ref: '#/components/schemas/UserSummary'
|
||
- type: 'null'
|
||
group_id:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: uuid
|
||
usage_requirement:
|
||
type: string
|
||
enum:
|
||
- optional
|
||
- required
|
||
description: 仅系统规则可设置 required。
|
||
required:
|
||
- usage_requirement
|
||
ResourceError:
|
||
type: object
|
||
properties:
|
||
error:
|
||
type: object
|
||
properties:
|
||
code:
|
||
type: string
|
||
message:
|
||
type: string
|
||
references:
|
||
type:
|
||
- array
|
||
- 'null'
|
||
items:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
required:
|
||
- code
|
||
- message
|
||
required:
|
||
- error
|
||
ResourceTag:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
required:
|
||
- id
|
||
- name
|
||
OAuthConnectionConfig:
|
||
type: object
|
||
description: dynamic 模式只需 MCP URL,首次授权自动发现 OAuth 元数据并动态注册客户端;发现及注册结果由后端维护,同一 URL 的普通编辑保留结果,修改 URL 后重新发现。manual 或未指定模式时,授权与 Token URL 必填,Client ID 和 Registration URL 至少填写一个。后续授权与刷新复用客户端;不支持需要初始访问令牌的注册端点。
|
||
properties:
|
||
mode:
|
||
type: string
|
||
enum: ['', manual, dynamic]
|
||
description: 动态自动发现与传统手动配置分开;未指定时沿用已有手动端点配置。
|
||
resource:
|
||
type: string
|
||
readOnly: true
|
||
description: 自动发现的资源标识,授权及 Token 请求携带此 resource 参数。
|
||
authorization_url:
|
||
type: string
|
||
token_url:
|
||
type: string
|
||
client_id:
|
||
type: string
|
||
registration_url:
|
||
type: string
|
||
description: RFC 7591 动态客户端注册端点;已有 Client ID 时复用,动态注册密钥到期后在下次授权前重新注册,旧客户端对应的凭证需重新授权。
|
||
token_endpoint_auth_method:
|
||
type: string
|
||
enum: ['', none, client_secret_post, client_secret_basic]
|
||
description: 自动发现模式按服务端元数据选择认证方式,优先 none;手动端点配置留空时,动态注册请求 none,已有客户端沿用 client_secret_post;注册后保存服务端返回的方式。
|
||
client_secret_expires_at:
|
||
type: integer
|
||
format: int64
|
||
readOnly: true
|
||
description: 注册服务器返回的客户端密钥到期时间(Unix 秒);未返回或为 0 表示无已知期限,由后端维护,修改请求中的值被忽略。
|
||
scopes:
|
||
type: string
|
||
ResourceIssue:
|
||
type: object
|
||
properties:
|
||
code:
|
||
type: string
|
||
blocking:
|
||
type: boolean
|
||
connector_id:
|
||
type: string
|
||
format: uuid
|
||
required:
|
||
- code
|
||
- blocking
|
||
MCPToolSetting:
|
||
type: object
|
||
required: [id, name, enabled, credits_per_call]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
name: {type: string}
|
||
enabled: {type: boolean}
|
||
credits_per_call: {type: number, minimum: 0}
|
||
MCPTool:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
description: 普通 MCP 保留已有 UUID,未配置工具使用稳定 UUID;内置知识库沿用工具名称作为 ID。
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
input_schema:
|
||
type: object
|
||
enabled:
|
||
type: boolean
|
||
credits_per_call:
|
||
type: number
|
||
minimum: 0
|
||
required:
|
||
- id
|
||
- name
|
||
- description
|
||
- input_schema
|
||
- enabled
|
||
- credits_per_call
|
||
AgentRule:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
content:
|
||
type: string
|
||
sha256:
|
||
type: string
|
||
required:
|
||
type: boolean
|
||
required:
|
||
- id
|
||
- name
|
||
- content
|
||
- sha256
|
||
- required
|
||
AgentSkill:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
package_sha256:
|
||
type: string
|
||
package_size_bytes:
|
||
type: integer
|
||
file_count:
|
||
type: integer
|
||
download_path:
|
||
type: string
|
||
tags:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceTag'
|
||
required:
|
||
- id
|
||
- name
|
||
- description
|
||
- package_sha256
|
||
- download_path
|
||
AgentConnector:
|
||
type: object
|
||
properties:
|
||
tags:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ResourceTag'}
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
icon_path:
|
||
type: string
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
name_i18n:
|
||
type: object
|
||
additionalProperties: {type: string}
|
||
description_i18n:
|
||
type: object
|
||
additionalProperties: {type: string}
|
||
authorization_mode:
|
||
type: string
|
||
enum:
|
||
- none
|
||
- centralized
|
||
- independent
|
||
authorization_method:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
authorization_status:
|
||
type: string
|
||
enum:
|
||
- not_required
|
||
- authorized
|
||
- authorization_required
|
||
connection_status:
|
||
type: string
|
||
capabilities:
|
||
type: array
|
||
items:
|
||
type: string
|
||
enum:
|
||
- catalog
|
||
- invoke
|
||
tools:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/MCPTool'
|
||
description: 实时启用工具,字段结构兼容旧客户端;无工具时为 []。独立认证目录在 credentials 内返回,resolve 和预览提升所选凭证的工具。
|
||
tools_version:
|
||
type: string
|
||
description: tools 内容的哈希;专家清单和预览基于服务端过滤后的工具计算。
|
||
credentials:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AgentCredential'
|
||
mcp_gateway:
|
||
$ref: '#/components/schemas/MCPGateway'
|
||
credential_id:
|
||
type: string
|
||
format: uuid
|
||
description: 集中认证返回当前集中凭证 ID;独立认证在 resolve 选定后返回所选凭证 ID。
|
||
required:
|
||
type: boolean
|
||
required:
|
||
- id
|
||
- name
|
||
- authorization_mode
|
||
- capabilities
|
||
description: 连接列表保留空 tools 数组及对应 tools_version(独立认证在内嵌凭证下返回),不发起远端工具查询。专家 manifest、resolve 和专家预览保留 tools 与 tools_version。独立认证目录在 credentials 内返回当前用户每份凭证的状态和专属代理地址,resolve 和预览提升所选凭证的工具及网关;集中认证返回当前集中凭证的代理地址,免认证返回连接地址。服务端应用专家工具允许/拒绝规则,拒绝规则优先;远端工具查询故障记录日志并在对应连接或凭证标记 connection_status=error、返回空 tools,不阻断目录和预览,也不回退旧目录;API Key 全局创建。
|
||
AgentExpert:
|
||
type: object
|
||
properties:
|
||
tags:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ResourceTag'}
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
version:
|
||
type: string
|
||
manifest_path:
|
||
type: string
|
||
available:
|
||
type: boolean
|
||
issues:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceIssue'
|
||
required:
|
||
- id
|
||
- name
|
||
- version
|
||
- manifest_path
|
||
- available
|
||
- issues
|
||
ExpertManifest:
|
||
type: object
|
||
properties:
|
||
expert_id:
|
||
type: string
|
||
name:
|
||
type: string
|
||
prompt:
|
||
type: string
|
||
version:
|
||
type: string
|
||
available:
|
||
type: boolean
|
||
rules:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AgentRule'
|
||
skills:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AgentSkill'
|
||
connectors:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/AgentConnector'
|
||
issues:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceIssue'
|
||
required:
|
||
- expert_id
|
||
- prompt
|
||
- version
|
||
- available
|
||
- rules
|
||
- skills
|
||
- connectors
|
||
- issues
|
||
ResolveResources:
|
||
type: object
|
||
properties:
|
||
expert_id:
|
||
type: string
|
||
format: uuid
|
||
rule_ids:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
skill_ids:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
connector_bindings:
|
||
type: object
|
||
additionalProperties:
|
||
type: string
|
||
format: uuid
|
||
description: 本次已选择的独立 Connector ID 到凭证 ID;不会隐式选择连接。无绑定时恰好一个有效凭证才自动选择,多份返回 credential_selection_required。
|
||
connector_ids:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
OAuthAuthorization:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
authorization_url:
|
||
type: string
|
||
format: uri
|
||
expires_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
required:
|
||
- id
|
||
- authorization_url
|
||
- expires_at
|
||
AuthorizationStatus:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
status:
|
||
type: string
|
||
enum:
|
||
- pending
|
||
- processing
|
||
- succeeded
|
||
- failed
|
||
- expired
|
||
credential_id:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: uuid
|
||
expires_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
required:
|
||
- id
|
||
- status
|
||
CredentialInput:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 128
|
||
http_headers:
|
||
type: object
|
||
minProperties: 1
|
||
maxProperties: 30
|
||
additionalProperties:
|
||
type: string
|
||
writeOnly: true
|
||
description: 完整 Header 键值;禁止大小写重复、CR/LF、Host、传输控制、Mcp-*、Content-Type 和 Accept。整组替换,响应不回填。
|
||
required:
|
||
- name
|
||
- http_headers
|
||
RuleResource:
|
||
type: object
|
||
properties:
|
||
description:
|
||
type: string
|
||
tags:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ResourceTag'}
|
||
shared_users:
|
||
type: array
|
||
readOnly: true
|
||
items:
|
||
$ref: '#/components/schemas/UserSummary'
|
||
description: 个人规则已共享的用户;未共享时为 [],系统规则不返回。
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
revision:
|
||
type: integer
|
||
minimum: 1
|
||
ownership_type:
|
||
type: string
|
||
enum:
|
||
- system
|
||
- user
|
||
user:
|
||
$ref: '#/components/schemas/UserSummary'
|
||
readOnly: true
|
||
description: 资源所有者的基本信息;系统资源返回创建者,分享不改变归属。
|
||
icon_path:
|
||
type: string
|
||
enabled:
|
||
type: boolean
|
||
grants:
|
||
description: 系统规则的授权范围及强制性:required 不可关闭,optional 默认开启但可由 Agent 关闭;个人规则可向指定用户共享只读使用权,不可强制应用。
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
updated_at:
|
||
type: string
|
||
format: date-time
|
||
content:
|
||
type: string
|
||
required:
|
||
- id
|
||
- name
|
||
- revision
|
||
- grants
|
||
RuleInput:
|
||
type: object
|
||
properties:
|
||
description:
|
||
type: string
|
||
tag_ids:
|
||
type: array
|
||
items: {type: string, format: uuid}
|
||
description: 替换系统规则的标签;省略时保留已有标签,空数组清空标签。
|
||
content:
|
||
type: string
|
||
name:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 200
|
||
grants:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
required:
|
||
- name
|
||
- content
|
||
SkillResource:
|
||
type: object
|
||
properties:
|
||
shared_users:
|
||
type: array
|
||
readOnly: true
|
||
items:
|
||
$ref: '#/components/schemas/UserSummary'
|
||
description: 仅资源所有者和管理端读取个人资源时返回共享用户列表,未共享时为 [],排除已删除用户;接收方和系统资源不返回。目录中的用户信息变化会更新 ETag。
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
revision:
|
||
type: integer
|
||
minimum: 1
|
||
ownership_type:
|
||
type: string
|
||
enum:
|
||
- system
|
||
- user
|
||
user:
|
||
$ref: '#/components/schemas/UserSummary'
|
||
readOnly: true
|
||
description: 资源所有者的基本信息;系统资源返回创建者,分享不改变归属。
|
||
icon_path:
|
||
type: string
|
||
enabled:
|
||
type: boolean
|
||
grants:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
updated_at:
|
||
type: string
|
||
format: date-time
|
||
description:
|
||
type: string
|
||
package_file_name:
|
||
type: string
|
||
package_sha256:
|
||
type: string
|
||
package_size_bytes:
|
||
type: integer
|
||
file_count:
|
||
type: integer
|
||
tags:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceTag'
|
||
required:
|
||
- id
|
||
- name
|
||
- revision
|
||
- grants
|
||
SkillInput:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
description:
|
||
type: string
|
||
content:
|
||
type: string
|
||
tag_ids:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
grants:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
required:
|
||
- name
|
||
ExpertResource:
|
||
type: object
|
||
properties:
|
||
avatar_path:
|
||
type: string
|
||
readOnly: true
|
||
description: 带版本参数的专家头像相对地址,未设置时省略;对象存储键不会对外返回。
|
||
tags:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ResourceTag'}
|
||
shared_users:
|
||
type: array
|
||
readOnly: true
|
||
items:
|
||
$ref: '#/components/schemas/UserSummary'
|
||
description: 仅资源所有者和管理端读取个人资源时返回共享用户列表,未共享时为 [],排除已删除用户;接收方和系统资源不返回。目录中的用户信息变化会更新 ETag。
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
revision:
|
||
type: integer
|
||
minimum: 1
|
||
ownership_type:
|
||
type: string
|
||
enum:
|
||
- system
|
||
- user
|
||
user:
|
||
$ref: '#/components/schemas/UserSummary'
|
||
readOnly: true
|
||
description: 资源所有者的基本信息;系统资源返回创建者,分享不改变归属。
|
||
icon_path:
|
||
type: string
|
||
enabled:
|
||
type: boolean
|
||
grants:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
updated_at:
|
||
type: string
|
||
format: date-time
|
||
description:
|
||
type: string
|
||
prompt:
|
||
type: string
|
||
rule_ids:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
skill_ids:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
connectors:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ConnectorDependency'
|
||
required:
|
||
- id
|
||
- name
|
||
- revision
|
||
- grants
|
||
ExpertAvatarForm:
|
||
type: object
|
||
description: 头像与专家字段在同一事务内保存。metadata 为 ExpertInput 的 JSON 字符串,avatar 为图片文件。未更换头像时继续发送 application/json,保留原头像。资源包原专家不允许修改头像;更新仍需 If-Match。
|
||
required: [metadata, avatar]
|
||
properties:
|
||
metadata:
|
||
type: string
|
||
description: ExpertInput 对象的 JSON 字符串,最多 1 MiB。
|
||
avatar:
|
||
type: string
|
||
format: binary
|
||
description: PNG、JPG/JPEG 或 WebP 图片,最多 1 MiB;服务端验证真实格式及完整图片内容。
|
||
ExpertInput:
|
||
type: object
|
||
properties:
|
||
tag_ids:
|
||
type: array
|
||
items: {type: string, format: uuid}
|
||
description:
|
||
type: string
|
||
prompt:
|
||
type: string
|
||
rule_ids:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
skill_ids:
|
||
type: array
|
||
items:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 200
|
||
grants:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
connectors:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ConnectorDependency'
|
||
required:
|
||
- name
|
||
- prompt
|
||
ConnectorResource:
|
||
type: object
|
||
properties:
|
||
tags:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ResourceTag'}
|
||
shared_users:
|
||
type: array
|
||
readOnly: true
|
||
items:
|
||
$ref: '#/components/schemas/UserSummary'
|
||
description: 仅资源所有者和管理端读取个人资源时返回共享用户列表,未共享时为 [],排除已删除用户;接收方和系统资源不返回。目录中的用户信息变化会更新 ETag。
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
name_i18n:
|
||
type: object
|
||
additionalProperties: {type: string}
|
||
description_i18n:
|
||
type: object
|
||
additionalProperties: {type: string}
|
||
revision:
|
||
type: integer
|
||
minimum: 1
|
||
ownership_type:
|
||
type: string
|
||
enum:
|
||
- system
|
||
- user
|
||
user:
|
||
$ref: '#/components/schemas/UserSummary'
|
||
readOnly: true
|
||
description: 资源所有者的基本信息;系统资源返回创建者,分享不改变归属。
|
||
icon_path:
|
||
type: string
|
||
enabled:
|
||
type: boolean
|
||
grants:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
updated_at:
|
||
type: string
|
||
format: date-time
|
||
description:
|
||
type: string
|
||
url:
|
||
type: string
|
||
format: uri
|
||
proxy_id:
|
||
type: string
|
||
description: 系统代理资源 ID;空字符串表示直连。
|
||
authorization_mode:
|
||
type: string
|
||
enum:
|
||
- none
|
||
- centralized
|
||
- independent
|
||
authorization_method:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
oauth_config:
|
||
$ref: '#/components/schemas/OAuthConnectionConfig'
|
||
callback_url:
|
||
type: string
|
||
readOnly: true
|
||
description: OAuth MCP 的专属完整回调地址,格式为 {MONKEYAI_PUBLIC_URL}/oauth/connectors/{id}/callback;非 OAuth 连接为空字符串。
|
||
config_revision:
|
||
type: integer
|
||
credential_configured:
|
||
type: boolean
|
||
connection_status:
|
||
type: string
|
||
credentials:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ConnectorCredential'
|
||
required:
|
||
- id
|
||
- name
|
||
- revision
|
||
- grants
|
||
- callback_url
|
||
ConnectorInput:
|
||
type: object
|
||
properties:
|
||
credential:
|
||
$ref: '#/components/schemas/ConnectorCredentialInput'
|
||
tag_ids:
|
||
type: array
|
||
items: {type: string, format: uuid}
|
||
description:
|
||
type: string
|
||
url:
|
||
type: string
|
||
format: uri
|
||
name:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 200
|
||
grants:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
authorization_mode:
|
||
type: string
|
||
enum:
|
||
- none
|
||
- centralized
|
||
- independent
|
||
authorization_method:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
enum:
|
||
- oauth
|
||
- http_header
|
||
- null
|
||
oauth_config:
|
||
$ref: '#/components/schemas/OAuthConnectionConfig'
|
||
oauth_client_secret:
|
||
type: string
|
||
writeOnly: true
|
||
description: 省略保留,空字符串清空;应用或端点变更时省略会清除旧 Secret。
|
||
anyOf:
|
||
- required: [name]
|
||
- required: [credential]
|
||
ConnectorCredentialInput:
|
||
type: object
|
||
additionalProperties: false
|
||
writeOnly: true
|
||
description: 仅集中认证支持。新增时提供 name,Header 凭证还需 http_headers;OAuth 可先创建待认证凭证。修改既有凭证必须同时提供 id、revision。省略字段保留原值;http_headers 中已有名称的空字符串值保留对应旧值,名称忽略大小写,新增名称必须提供非空值,未提交的旧名称会删除;空对象表示清空 Header 并撤销当前 Header 凭证,无凭证时为空操作。撤销只接受 id、revision、revoke=true。实际 OAuth Token 只能通过授权流程写入。
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
revision:
|
||
type: integer
|
||
minimum: 1
|
||
name:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 128
|
||
http_headers:
|
||
type: object
|
||
writeOnly: true
|
||
minProperties: 0
|
||
maxProperties: 30
|
||
additionalProperties:
|
||
type: string
|
||
revoke:
|
||
type: boolean
|
||
default: false
|
||
dependentRequired:
|
||
id: [revision]
|
||
revision: [id]
|
||
anyOf:
|
||
- required: [name]
|
||
- required: [http_headers]
|
||
- required: [id, revision, revoke]
|
||
properties:
|
||
revoke:
|
||
const: true
|
||
AgentCredential:
|
||
allOf:
|
||
- $ref: '#/components/schemas/ConnectorCredential'
|
||
- type: object
|
||
properties:
|
||
tools:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/MCPTool'
|
||
tools_version:
|
||
type: string
|
||
mcp_gateway:
|
||
$ref: '#/components/schemas/MCPGateway'
|
||
AuthorizationName:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 128
|
||
required:
|
||
- name
|
||
ConnectorCredential:
|
||
type: object
|
||
properties:
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
connector_id:
|
||
type: string
|
||
format: uuid
|
||
user:
|
||
oneOf:
|
||
- $ref: '#/components/schemas/UserSummary'
|
||
- type: 'null'
|
||
readOnly: true
|
||
description: 凭证所属的平台用户基本信息;集中凭证为 null,不读取上游 OAuth 用户资料。
|
||
name:
|
||
type: string
|
||
revision:
|
||
type: integer
|
||
config_revision:
|
||
type: integer
|
||
authorization_status:
|
||
type: string
|
||
enum:
|
||
- authorized
|
||
- authorization_required
|
||
- revoked
|
||
connection_status:
|
||
type: string
|
||
enum:
|
||
- unknown
|
||
- connected
|
||
- error
|
||
header_names:
|
||
type: array
|
||
items:
|
||
type: string
|
||
last_checked_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
last_error:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
oauth_expires_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
created_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
updated_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
revoked_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
required:
|
||
- id
|
||
- connector_id
|
||
- user
|
||
- name
|
||
- revision
|
||
- authorization_status
|
||
- connection_status
|
||
ConnectorDependency:
|
||
type: object
|
||
properties:
|
||
required:
|
||
type: boolean
|
||
tool_allowlist:
|
||
type: array
|
||
items:
|
||
type: string
|
||
tool_denylist:
|
||
type: array
|
||
items:
|
||
type: string
|
||
connector_id:
|
||
type: string
|
||
format: uuid
|
||
required:
|
||
- connector_id
|
||
CredentialPatch:
|
||
type: object
|
||
properties:
|
||
name:
|
||
type: string
|
||
minLength: 1
|
||
maxLength: 128
|
||
http_headers:
|
||
type: object
|
||
minProperties: 1
|
||
maxProperties: 30
|
||
additionalProperties:
|
||
type: string
|
||
writeOnly: true
|
||
description: 完整 Header 键值;禁止大小写重复、CR/LF、Host、传输控制、Mcp-*、Content-Type 和 Accept。整组替换,响应不回填。
|
||
minProperties: 1
|
||
MCPGateway:
|
||
type: object
|
||
properties:
|
||
url:
|
||
type: string
|
||
format: uri
|
||
description: 以 /mcp 为前缀:免认证为 /mcp/connectors/{id},集中或独立认证为 /mcp/connectors/{id}/credentials/{credential_id}。全局 API Key
|
||
认证用户,服务端校验地址对应连接使用权、凭证归属和有效性。
|
||
transport:
|
||
const: streamable_http
|
||
authentication:
|
||
const: api_key
|
||
required_scope:
|
||
const: mcp:invoke
|
||
required:
|
||
- url
|
||
- transport
|
||
- authentication
|
||
- required_scope
|
||
KbInput:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [name]
|
||
properties:
|
||
name: {type: string, minLength: 1, maxLength: 200}
|
||
description: {type: string}
|
||
enabled: {type: boolean}
|
||
fusion_config: {$ref: '#/components/schemas/KbFusionConfig'}
|
||
tag_ids: {type: array, items: {type: string, format: uuid}}
|
||
grants:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
user_id: {type: string, format: uuid}
|
||
group_id: {type: string, format: uuid}
|
||
all_users: {type: boolean}
|
||
usage_requirement:
|
||
type: string
|
||
enum: [optional]
|
||
default: optional
|
||
description: 知识库授权仅支持 optional;required 仅用于系统规则。
|
||
Kb:
|
||
type: object
|
||
required: [id, name, description, ownership_type, enabled, revision, embedding_model_id, embedding_dimension, fusion_config, embedding_configured, capabilities, index_job_summary, document_count, learned_count, tags, grants, updated_at]
|
||
properties:
|
||
avatar_path:
|
||
type: string
|
||
description: 受权限保护的图标读取路径 /api/admin/v1/kb/{id}/avatar,包含图片版本参数;无图标时为空或省略。
|
||
id: {type: string, format: uuid}
|
||
name: {type: string}
|
||
description: {type: string}
|
||
ownership_type: {type: string, enum: [system, user]}
|
||
enabled: {type: boolean}
|
||
revision: {type: integer}
|
||
embedding_model_id: {type: [string, 'null'], format: uuid}
|
||
embedding_dimension: {type: [integer, 'null']}
|
||
fusion_config: {$ref: '#/components/schemas/KbFusionConfig'}
|
||
embedding_configured: {type: boolean}
|
||
capabilities: {$ref: '#/components/schemas/KbIndexCapabilities'}
|
||
index_job_summary: {$ref: '#/components/schemas/KbIndexJobSummary'}
|
||
document_count: {type: integer}
|
||
learned_count: {type: integer}
|
||
tags: {type: array, items: {type: object}}
|
||
grants: {type: array, items: {type: object}}
|
||
notice: {type: string, description: 模型切换等操作返回的提示信息。}
|
||
updated_at: {type: string, format: date-time}
|
||
KbDocumentInput:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [title]
|
||
properties:
|
||
expected_revision: {type: integer, minimum: 1, description: 可选文档版本,提供时校验冲突。}
|
||
title: {type: string, minLength: 1}
|
||
parent_id: {type: [string, 'null'], format: uuid}
|
||
node_type: {type: string, enum: [folder, document], default: document}
|
||
source_type: {type: string, enum: [text, file, url]}
|
||
content: {type: string}
|
||
file_name: {type: string}
|
||
mime_type: {type: string}
|
||
size_bytes: {type: integer, minimum: 0}
|
||
KbDocumentDeleteInput:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [ids]
|
||
properties:
|
||
ids: {type: array, minItems: 1, maxItems: 200, items: {type: string, format: uuid}}
|
||
expected_revisions: {type: object, additionalProperties: {type: integer, minimum: 1}}
|
||
KbDocumentOperationResult:
|
||
type: object
|
||
required: [succeeded, failed]
|
||
properties:
|
||
succeeded: {type: array, items: {type: string, format: uuid}}
|
||
failed:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required: [id, reason]
|
||
properties:
|
||
id: {type: string}
|
||
reason: {type: string}
|
||
KbDocumentMoveInput:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [ids]
|
||
properties:
|
||
ids: {type: array, minItems: 1, maxItems: 200, items: {type: string, format: uuid}}
|
||
expected_revisions: {type: object, additionalProperties: {type: integer, minimum: 1}}
|
||
parent_id: {type: [string, 'null'], format: uuid}
|
||
prev_id: {type: string, format: uuid, description: 指定相邻节点排序时 ids 只能含一个 ID。}
|
||
next_id: {type: string, format: uuid, description: 指定相邻节点排序时 ids 只能含一个 ID。}
|
||
|
||
KbDocument:
|
||
type: object
|
||
required: [id, kb_id, node_type, title, source_type, content, status, chunk_count, revision, created_at, updated_at]
|
||
properties:
|
||
updated_by_user_id: {type: [string, 'null'], format: uuid}
|
||
content_updated_at: {type: [string, 'null'], format: date-time}
|
||
id: {type: string, format: uuid}
|
||
kb_id: {type: string, format: uuid}
|
||
parent_id: {type: [string, 'null'], format: uuid}
|
||
node_type: {type: string, enum: [folder, document]}
|
||
position: {type: number}
|
||
children: {type: array, items: {$ref: '#/components/schemas/KbDocument'}}
|
||
title: {type: string}
|
||
source_type: {type: string, enum: [text, file, url]}
|
||
content: {type: string}
|
||
file_name: {type: [string, 'null']}
|
||
mime_type: {type: [string, 'null']}
|
||
size_bytes: {type: integer}
|
||
status: {type: string, enum: [pending, learning, learned, failed]}
|
||
error_message: {type: [string, 'null']}
|
||
chunk_count: {type: integer}
|
||
revision: {type: integer}
|
||
learned_at: {type: [string, 'null'], format: date-time}
|
||
created_at: {type: string, format: date-time}
|
||
updated_at: {type: string, format: date-time}
|
||
KbChunk:
|
||
type: object
|
||
required: [chunk_id, kb_id, document_id, chunk_index, content]
|
||
properties:
|
||
chunk_id: {type: string, format: uuid}
|
||
kb_id: {type: string, format: uuid}
|
||
document_id: {type: string, format: uuid}
|
||
chunk_index: {type: integer}
|
||
content: {type: string}
|
||
token_count: {type: [integer, 'null']}
|
||
has_vector: {type: boolean}
|
||
embedding_model_id: {type: [string, 'null'], format: uuid}
|
||
heading_path: {type: [string, 'null']}
|
||
page_no: {type: [integer, 'null']}
|
||
source_url: {type: [string, 'null']}
|
||
created_at: {type: string, format: date-time}
|
||
updated_at: {type: string, format: date-time}
|
||
KbSearchInput:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [query]
|
||
properties:
|
||
kb_ids: {type: array, maxItems: 50, items: {type: string, format: uuid}}
|
||
query: {type: string, minLength: 1}
|
||
top_k: {type: integer, minimum: 1, maximum: 20, default: 8}
|
||
filters: {type: object, additionalProperties: true, description: 当前版本保留字段,暂不参与过滤。}
|
||
KbSearchResult:
|
||
type: object
|
||
required: [kb_id, document_id, chunk_id, chunk_index, content, title, score, retrieval_source, citation]
|
||
properties:
|
||
kb_id: {type: string, format: uuid}
|
||
document_id: {type: string, format: uuid}
|
||
chunk_id: {type: string, format: uuid}
|
||
chunk_index: {type: integer}
|
||
content: {type: string}
|
||
title: {type: string}
|
||
score: {type: number}
|
||
retrieval_source: {type: string, enum: [lexical, vector, both]}
|
||
citation: {$ref: '#/components/schemas/KbCitation'}
|
||
KbFusionConfig:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [type, k, weights]
|
||
properties:
|
||
type: {type: string, enum: [weighted_rrf]}
|
||
k: {type: integer, minimum: 1, default: 60}
|
||
weights:
|
||
type: object
|
||
required: [lexical, vector]
|
||
additionalProperties: false
|
||
properties:
|
||
lexical: {type: number, minimum: 0, default: 0.3}
|
||
vector: {type: number, minimum: 0, default: 0.7}
|
||
KbIndexCapabilities:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [search_modes, channels, embedding_configured]
|
||
properties:
|
||
search_modes: {type: array, items: {type: string, enum: [lexical, hybrid]}}
|
||
channels: {type: array, items: {type: string, enum: [lexical, vector]}}
|
||
embedding_configured: {type: boolean}
|
||
KbIndexJobSummary:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [pending, running, failed, by_operation]
|
||
properties:
|
||
pending: {type: integer}
|
||
running: {type: integer}
|
||
failed: {type: integer}
|
||
by_operation:
|
||
type: object
|
||
additionalProperties:
|
||
type: object
|
||
additionalProperties: {type: integer}
|
||
KbCitation:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [heading_path, page_no, source_url]
|
||
properties:
|
||
heading_path: {type: [string, 'null']}
|
||
page_no: {type: [integer, 'null']}
|
||
source_url: {type: [string, 'null']}
|
||
KbSearchResponse:
|
||
type: object
|
||
required: [query, retrieval_mode, channels_used, fusion, degraded, warnings, items]
|
||
properties:
|
||
query: {type: string}
|
||
retrieval_mode: {type: string, enum: [lexical, hybrid, vector]}
|
||
channels_used: {type: array, items: {type: string, enum: [lexical, vector]}}
|
||
fusion:
|
||
type: object
|
||
description: 单库或参数一致时为 weighted_rrf 配置;不一致时返回 k_by_kb 与 weights_by_kb。
|
||
additionalProperties: true
|
||
degraded: {type: boolean}
|
||
warnings: {type: array, items: {type: string}}
|
||
items: {type: array, items: {$ref: '#/components/schemas/KbSearchResult'}}
|
||
EnvironmentBillingConfig:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [cpu_credits_per_core_hour, memory_credits_per_gib_hour]
|
||
description: 全局配置,适用于所有宿主机,无计费开关。CPU 默认每核每小时100积分,内存默认每GB每小时50积分(GB=1024³字节),不继承旧宿主计价;仅通过费用设置保存,零单价不扣积分。启动前按分配CPU和内存预扣完整一小时,到期续扣;提前停止不退款,已付费期限内重启不重复扣费。存储暂不收费,仅支持本地积分。调价从下一次续费生效,历史按秒账单仍按已确认用量结清。
|
||
properties:
|
||
cpu_credits_per_core_hour:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
memory_credits_per_gib_hour:
|
||
$ref: '#/components/schemas/CreditAmount'
|
||
HostGrantInput:
|
||
type: object
|
||
additionalProperties: false
|
||
description: 每条仅指定用户、分组或全员之一;根分组代表全员,空数组代表不允许任何用户新建或启动。撤回不影响已有运行与连接。
|
||
properties:
|
||
user_id: {type: string, format: uuid}
|
||
group_id: {type: string, format: uuid}
|
||
all_users: {type: boolean}
|
||
usage_requirement: {type: string, enum: [optional]}
|
||
EnvironmentSpecificationCatalogInput:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [revision, items]
|
||
properties:
|
||
revision: {type: integer, format: int64, minimum: 0}
|
||
items:
|
||
type: array
|
||
maxItems: 100
|
||
items:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [id, version, cpu_millis, memory_bytes]
|
||
properties:
|
||
id: {type: string, format: uuid, pattern: '^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$'}
|
||
version: {type: integer, format: int64, minimum: 0, description: 新增为0,已有项携带最新版本}
|
||
cpu_millis: {type: integer, format: int64, minimum: 100, maximum: 256000}
|
||
memory_bytes: {type: integer, format: int64, minimum: 268435456, maximum: 1099511627776}
|
||
EnvironmentSetupInput:
|
||
type: object
|
||
additionalProperties: false
|
||
properties:
|
||
name: {type: string, maxLength: 128, description: 去除首尾空白后最多 128 个 UTF-8 字节。省略时保留原名,清空后由下一次有效宿主名称上报补全。}
|
||
grants:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/HostGrantInput'}
|
||
description: 省略时保留现有范围;显式空数组撤回全部新建/启动权限,不打断已有环境。
|
||
EnvironmentSetup:
|
||
type: object
|
||
description: 当前宿主独立保存授权范围,不设置环境数量上限。CPU/内存规格独立全局管理;billing 为只读全局计费配置,须到费用设置统一修改。
|
||
required: [host_id, host_name, capacity, image_ready, billing, grants]
|
||
properties:
|
||
host_id: {type: string, format: uuid}
|
||
host_name: {type: string}
|
||
grants:
|
||
type: array
|
||
items: {$ref: '#/components/schemas/ResourceGrant'}
|
||
capacity:
|
||
$ref: '#/components/schemas/EnvironmentCapacity'
|
||
image_ready:
|
||
type: boolean
|
||
description: server默认镜像是否已准备当前宿主架构;不影响保存授权,但未就绪不能创建环境。
|
||
image_reason:
|
||
type: string
|
||
description: 默认镜像未就绪的原因。
|
||
billing:
|
||
$ref: '#/components/schemas/EnvironmentBillingConfig'
|
||
HostSystem:
|
||
type: object
|
||
description: 宿主整机信息;CPU 为相邻心跳采样间使用率,首次或计数失效时省略。内存使用量为总量减 MemAvailable;磁盘为 data_dir 所在文件系统,已用量不含保留块,可用量扣除保留块。采集失败的分组省略,不代表零占用。
|
||
properties:
|
||
private_ips:
|
||
type: array
|
||
maxItems: 64
|
||
description: 活跃宿主网卡的内网 IPv4/IPv6 地址,排除容器虚拟接口;包括 CGNAT 地址。
|
||
items: {type: string}
|
||
public_ips:
|
||
type: array
|
||
maxItems: 64
|
||
description: 活跃宿主网卡的公网地址;管理端额外合并后台观察到的公网连接来源,不代表可入站访问。
|
||
items: {type: string}
|
||
network:
|
||
type: object
|
||
description: 宿主非容器网卡的区间平均收发速率,排除回环及 bridge/bond 从接口。首次采样、计数回退或网卡集合变化时省略。
|
||
required: [receive_bytes_per_second, transmit_bytes_per_second]
|
||
properties:
|
||
receive_bytes_per_second: {type: number, minimum: 0}
|
||
transmit_bytes_per_second: {type: number, minimum: 0}
|
||
disk_io:
|
||
type: object
|
||
description: 数据目录所在块设备的区间平均读写速率,包含该设备上其他进程的 I/O。首次采样、计数回退、设备变化或非块设备文件系统时省略。
|
||
required: [read_bytes_per_second, write_bytes_per_second]
|
||
properties:
|
||
read_bytes_per_second: {type: number, minimum: 0}
|
||
write_bytes_per_second: {type: number, minimum: 0}
|
||
hostname: {type: string, maxLength: 255}
|
||
os_name: {type: string, maxLength: 256}
|
||
kernel_version: {type: string, maxLength: 256}
|
||
cpu:
|
||
type: object
|
||
required: [model, logical_cores]
|
||
properties:
|
||
model: {type: string, maxLength: 512}
|
||
logical_cores: {type: integer, minimum: 1, maximum: 1048576}
|
||
usage_percent: {type: number, minimum: 0, maximum: 100}
|
||
memory:
|
||
$ref: '#/components/schemas/HostMemory'
|
||
disk:
|
||
allOf:
|
||
- $ref: '#/components/schemas/HostMemory'
|
||
- type: object
|
||
required: [path]
|
||
properties:
|
||
path: {type: string, maxLength: 4096, pattern: '^/'}
|
||
HostMemory:
|
||
type: object
|
||
required: [total_bytes, used_bytes, available_bytes]
|
||
properties:
|
||
total_bytes: {type: integer, format: int64, minimum: 1}
|
||
used_bytes: {type: integer, format: int64, minimum: 0}
|
||
available_bytes: {type: integer, format: int64, minimum: 0}
|
||
EnvironmentUsage:
|
||
type: object
|
||
description: 当前实例最近一次 Docker CPU/内存采样;只存最新值,不保存历史。采集失败或旧 engine 可省略,不能将缺失视为零。超过 90 秒的样本应标记过期。
|
||
required: [at]
|
||
properties:
|
||
at: {type: string, format: date-time}
|
||
cpu_cores:
|
||
type: number
|
||
minimum: 0
|
||
maximum: 1048576
|
||
description: CPU 使用核数,1 表示占满一个逻辑核;展示百分比时除以配置核数。
|
||
memory_bytes:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
description: Docker 内存使用量,排除 inactive file 缓存;包含 gVisor 沙箱开销。
|
||
additionalProperties: false
|
||
Environment:
|
||
type: object
|
||
required:
|
||
- id
|
||
- user_id
|
||
- host_id
|
||
- name
|
||
- generation
|
||
- instance_id
|
||
- desired
|
||
- phase
|
||
- observed_generation
|
||
- observed_at
|
||
- reason
|
||
- storage_retained
|
||
- workload_verified
|
||
- spec
|
||
- created_at
|
||
- deleted_at
|
||
properties:
|
||
runtime_version:
|
||
type: string
|
||
description: 最近一次宿主上报的 runtime 版本,未知为空。
|
||
usage_stale:
|
||
type: boolean
|
||
description: 仅详情返回,最新资源样本超过 90 秒时为 true;省略表示 false,不能当作当前实时值。
|
||
usage:
|
||
$ref: '#/components/schemas/EnvironmentUsage'
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
user_id:
|
||
type: string
|
||
format: uuid
|
||
host_id:
|
||
type: string
|
||
format: uuid
|
||
user:
|
||
type: object
|
||
description: 管理端展示的所属用户信息
|
||
required: [name, email, avatar_url]
|
||
properties:
|
||
name:
|
||
type: string
|
||
email:
|
||
type: string
|
||
avatar_url:
|
||
type: string
|
||
host:
|
||
type: object
|
||
description: 管理端展示的宿主信息,hostname 未上报时为空
|
||
required: [name, hostname, os_name]
|
||
properties:
|
||
name:
|
||
type: string
|
||
hostname:
|
||
type: string
|
||
os_name:
|
||
type: string
|
||
name:
|
||
type: string
|
||
generation:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
instance_id:
|
||
type: string
|
||
format: uuid
|
||
desired:
|
||
type: string
|
||
enum:
|
||
- running
|
||
- stopped
|
||
- deleted
|
||
phase:
|
||
type: string
|
||
enum:
|
||
- pending
|
||
- preparing
|
||
- starting
|
||
- running
|
||
- stopping
|
||
- stopped
|
||
- deleting
|
||
- deleted
|
||
- failed
|
||
observed_generation:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
observed_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
reason:
|
||
type: string
|
||
enum:
|
||
- ''
|
||
- apply_failed
|
||
- inspect_failed
|
||
- process_exited
|
||
- local_state_conflict
|
||
- runtime_failed
|
||
- runtime_upgrade_failed
|
||
storage_retained:
|
||
type: boolean
|
||
const: true
|
||
workload_verified:
|
||
type: boolean
|
||
const: false
|
||
spec:
|
||
$ref: host.yaml#/components/schemas/EnvironmentSpec
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
archived_at:
|
||
type: string
|
||
format: date-time
|
||
description: 已从使用列表移除但仍待宿主清理的归档时间;仅在此状态存在,不代表宿主已删除。
|
||
deleted_at:
|
||
type: [string, 'null']
|
||
format: date-time
|
||
description: 宿主确认当前代次删除完成的时间;未完成或失败时为 null,历史记录继续保留。
|
||
description: phase 是最后一次观察结果,判断当前目标是否完成必须同时检查 observed_generation == generation。running 仅表示容器进程运行,尚不代表 runtime
|
||
登录或用户可连接。
|
||
SystemImage:
|
||
type: object
|
||
required: [id, display_name, added_at, status, source_type, progress, is_default, architectures]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
display_name: {type: string}
|
||
added_at: {type: string, format: date-time}
|
||
source_type: {enum: [builtin, pull, upload]}
|
||
status: {enum: [pending, importing, ready, failed]}
|
||
reference: {type: [string, 'null']}
|
||
upstream: {type: [string, 'null']}
|
||
archive_name: {type: [string, 'null']}
|
||
is_default: {type: boolean}
|
||
architectures: {type: array, items: {type: string}}
|
||
progress:
|
||
type: object
|
||
properties:
|
||
stage: {type: string}
|
||
completed_bytes: {type: integer}
|
||
total_bytes: {type: [integer, 'null']}
|
||
error:
|
||
type: [object, 'null']
|
||
properties:
|
||
code: {type: string}
|
||
message: {type: string}
|
||
EnvironmentImage:
|
||
type: object
|
||
required: [source, reference, status, architectures, updated_at]
|
||
properties:
|
||
source: {type: string}
|
||
reference: {type: string, description: server 镜像仓库的固定摘要引用。}
|
||
status: {type: string, enum: [syncing, ready, failed]}
|
||
architectures: {type: array, items: {type: string, enum: [amd64, arm64]}}
|
||
error: {type: string}
|
||
updated_at: {type: string, format: date-time}
|
||
EnvironmentRuntimeUpgrade:
|
||
type: object
|
||
required: [generation, request_key]
|
||
properties:
|
||
generation: {type: integer, format: int64, minimum: 1}
|
||
request_key: {type: string, minLength: 1, maxLength: 128}
|
||
version: {type: string, pattern: '^[0-9]{1,8}\.[0-9]{1,8}\.[0-9]{1,8}$'}
|
||
additionalProperties: false
|
||
EnvironmentRuntimeInfo:
|
||
type: object
|
||
required: [current_version, latest_version, update_available, can_update]
|
||
properties:
|
||
current_version: {type: string, description: 最近一次宿主上报的实际选择版本,未知为空。}
|
||
latest_version: {type: string, description: server 配置的发行版本,资源未配置或缺失时为空。}
|
||
target_version: {type: string}
|
||
update_available: {type: boolean}
|
||
can_update: {type: boolean}
|
||
reason: {type: string}
|
||
operation: {$ref: '#/components/schemas/EnvironmentOperation'}
|
||
EnvironmentOperation:
|
||
type: object
|
||
required:
|
||
- id
|
||
- environment_id
|
||
- generation
|
||
- desired
|
||
- status
|
||
- reason
|
||
- created_at
|
||
- finished_at
|
||
properties:
|
||
kind: {type: string, enum: [create, lifecycle, runtime_upgrade]}
|
||
target_version: {type: string}
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
environment_id:
|
||
type: string
|
||
format: uuid
|
||
generation:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
desired:
|
||
type: string
|
||
enum:
|
||
- running
|
||
- stopped
|
||
- deleted
|
||
status:
|
||
type: string
|
||
enum:
|
||
- pending
|
||
- succeeded
|
||
- failed
|
||
- superseded
|
||
reason:
|
||
type: string
|
||
enum:
|
||
- ''
|
||
- apply_failed
|
||
- inspect_failed
|
||
- process_exited
|
||
- local_state_conflict
|
||
- runtime_failed
|
||
- runtime_upgrade_failed
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
finished_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
EnvironmentChange:
|
||
type: object
|
||
required:
|
||
- generation
|
||
- request_key
|
||
properties:
|
||
generation:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
request_key:
|
||
type: string
|
||
pattern: ^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$
|
||
additionalProperties: false
|
||
EnvironmentResult:
|
||
type: object
|
||
required:
|
||
- environment
|
||
- operation
|
||
properties:
|
||
environment:
|
||
$ref: '#/components/schemas/Environment'
|
||
operation:
|
||
$ref: '#/components/schemas/EnvironmentOperation'
|
||
EnvironmentError:
|
||
type: object
|
||
required:
|
||
- error
|
||
properties:
|
||
error:
|
||
type: object
|
||
required:
|
||
- message
|
||
properties:
|
||
code:
|
||
type: string
|
||
message:
|
||
type: string
|
||
EnvironmentList:
|
||
type: object
|
||
required:
|
||
- items
|
||
- page
|
||
- page_size
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/Environment'
|
||
page:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
page_size:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
maximum: 100
|
||
EnvironmentOperationList:
|
||
type: object
|
||
required:
|
||
- items
|
||
- page
|
||
- page_size
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
$ref: '#/components/schemas/EnvironmentOperation'
|
||
page:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
page_size:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
maximum: 100
|
||
EnvironmentCapacityInput:
|
||
type: object
|
||
additionalProperties: false
|
||
required: [enabled]
|
||
properties:
|
||
enabled: {type: boolean}
|
||
EnvironmentCapacity:
|
||
description: CPU与内存是宿主硬件报告,仅用于监控,不作为准入容量;不设置环境数量上限,enabled控制是否允许新建调度。
|
||
type: object
|
||
required:
|
||
- enabled
|
||
- cpu_millis
|
||
- memory_bytes
|
||
properties:
|
||
enabled:
|
||
type: boolean
|
||
cpu_millis:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
maximum: 1048576000
|
||
memory_bytes:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
maximum: 9223372036854775807
|
||
additionalProperties: false
|
||
EnvironmentHost:
|
||
type: object
|
||
required:
|
||
- host_id
|
||
- enabled
|
||
- cpu_millis
|
||
- memory_bytes
|
||
- protocol
|
||
- sync_at
|
||
properties:
|
||
host_id:
|
||
type: string
|
||
format: uuid
|
||
enabled:
|
||
type: boolean
|
||
cpu_millis:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
maximum: 4096000
|
||
memory_bytes:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
maximum: 17592186044416
|
||
protocol:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
sync_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
EnvironmentHostList:
|
||
type: object
|
||
required:
|
||
- items
|
||
- page
|
||
- page_size
|
||
properties:
|
||
items:
|
||
type: array
|
||
items:
|
||
type: object
|
||
required:
|
||
- host_id
|
||
- enabled
|
||
- cpu_millis
|
||
- memory_bytes
|
||
- protocol
|
||
- sync_at
|
||
- architecture
|
||
- status
|
||
- last_seen_at
|
||
properties:
|
||
host_id:
|
||
type: string
|
||
format: uuid
|
||
enabled:
|
||
type: boolean
|
||
cpu_millis:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
maximum: 4096000
|
||
memory_bytes:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
maximum: 17592186044416
|
||
protocol:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
sync_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
architecture:
|
||
type: string
|
||
enum:
|
||
- amd64
|
||
- arm64
|
||
status:
|
||
type: string
|
||
enum:
|
||
- pending
|
||
- active
|
||
- revoked
|
||
last_seen_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
page:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
page_size:
|
||
type: integer
|
||
format: int64
|
||
minimum: 1
|
||
maximum: 100
|
||
EngineUpgradeTask:
|
||
type: object
|
||
required: [id, from_version, version, status, reason, created_at, updated_at]
|
||
properties:
|
||
id: {type: string, format: uuid}
|
||
from_version: {type: string, description: 创建升级任务时的当前engine版本快照}
|
||
version: {type: string}
|
||
status: {type: string, enum: [pending, running, succeeded, failed]}
|
||
reason: {type: string, enum: ['', launch_failed, upgrade_failed, upgrade_interrupted, upgrade_timeout]}
|
||
created_at: {type: string, format: date-time}
|
||
updated_at: {type: string, format: date-time}
|
||
EngineUpgrade:
|
||
type: object
|
||
required: [target_version, version_state, update_available, supported, can_upgrade, task]
|
||
properties:
|
||
target_version: {type: string}
|
||
version_state: {type: string, enum: [current, available, ahead, unknown]}
|
||
update_available: {type: boolean}
|
||
supported: {type: boolean, description: 宿主是否声明远程升级协议版本 1}
|
||
can_upgrade: {type: boolean, description: 在线、支持协议、有更高版本且没有活动任务;提交时再次检查发行资源}
|
||
task:
|
||
oneOf:
|
||
- {$ref: '#/components/schemas/EngineUpgradeTask'}
|
||
- {type: 'null'}
|
||
EngineHost:
|
||
type: object
|
||
required:
|
||
- grants
|
||
- id
|
||
- name
|
||
- architecture
|
||
- version
|
||
- status
|
||
- online
|
||
- user_id
|
||
- enabled
|
||
- activated_at
|
||
- last_seen_at
|
||
- report
|
||
- created_at
|
||
properties:
|
||
grants:
|
||
type: array
|
||
description: 宿主授权范围,包含用户或分组名称;全员授权使用虚拟根分组表示。
|
||
items:
|
||
$ref: '#/components/schemas/ResourceGrant'
|
||
environment_count:
|
||
type: integer
|
||
format: int64
|
||
minimum: 0
|
||
description: 仅装配云电脑模块时返回。该宿主尚未移除的环境数,包含停止、失败和在线等待删除的环境,与默认环境列表一致;不含离线归档记录。
|
||
user_id: {type: string, format: uuid, description: 创建宿主记录的用户}
|
||
enabled:
|
||
type: boolean
|
||
description: 是否允许新建环境调度;关闭不停止已有环境。
|
||
upgrade:
|
||
$ref: '#/components/schemas/EngineUpgrade'
|
||
id:
|
||
type: string
|
||
format: uuid
|
||
name:
|
||
type: string
|
||
architecture:
|
||
type: string
|
||
enum:
|
||
- amd64
|
||
- arm64
|
||
version:
|
||
type: string
|
||
status:
|
||
type: string
|
||
enum:
|
||
- pending
|
||
- active
|
||
- revoked
|
||
online:
|
||
type: boolean
|
||
activated_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
last_seen_at:
|
||
type:
|
||
- string
|
||
- 'null'
|
||
format: date-time
|
||
created_at:
|
||
type: string
|
||
format: date-time
|
||
report:
|
||
type: object
|
||
description: 未收到报告时为空对象;硬件字段来自宿主自报,不代表可信硬件证明。公网地址额外合并后台观察到的连接来源。
|
||
properties:
|
||
version:
|
||
type: integer
|
||
const: 1
|
||
upgrade_protocol:
|
||
type: integer
|
||
enum: [0, 1]
|
||
engine_version:
|
||
type: string
|
||
description: 实际运行的 engine 版本;签名心跳接受后同步更新宿主版本。
|
||
at:
|
||
type: string
|
||
format: date-time
|
||
system:
|
||
$ref: '#/components/schemas/HostSystem'
|
||
os:
|
||
type: string
|
||
architecture:
|
||
type: string
|
||
prerequisites_met:
|
||
type: boolean
|
||
workload_verified:
|
||
type: boolean
|
||
const: false
|
||
checks:
|
||
type: array
|
||
maxItems: 100
|
||
items:
|
||
type: object
|
||
required:
|
||
- name
|
||
- passed
|
||
- detail
|
||
properties:
|
||
name:
|
||
type: string
|
||
passed:
|
||
type: boolean
|
||
detail:
|
||
type: string
|
||
|