Files

11325 lines
405 KiB
YAML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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