Spaces:
Sleeping
Sleeping
Download docs/10_API_Gateway/openapi.json from dellweb3/workos-office: direct link, hf CLI and curl.
- Browser
- Download file 237 kB
-
https://huggingface.co/spaces/dellweb3/workos-office/resolve/main/docs/10_API_Gateway/openapi.json
- Command line
-
hf download hf://spaces/dellweb3/workos-office/docs/10_API_Gateway/openapi.json
-
curl -L -o openapi.json https://huggingface.co/spaces/dellweb3/workos-office/resolve/main/docs/10_API_Gateway/openapi.json
237 kB
{
"openapi": "3.1.0",
"info": {
"title": "Work OS API Gateway PC design contract",
"version": "1.0.0",
"description": "PC 37 项设计契约;Gateway 已有演示实现,Workspace 已接持久化首版,其它下游服务仍为 fixture。"
},
"servers": [
{
"url": "http://127.0.0.1:8000",
"description": "PC loopback design target"
}
],
"security": [
{
"BearerAuth": []
}
],
"paths": {
"/api/v1/auth/login": {
"post": {
"operationId": "login",
"summary": "演示账号登录",
"tags": [
"Identity"
],
"x-owner-module": "Identity",
"x-required-scope": "public",
"parameters": [],
"responses": {
"200": {
"description": "演示账号登录",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Token"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LoginInput"
}
}
}
}
}
},
"/api/v1/auth/logout": {
"post": {
"operationId": "logout",
"summary": "撤销当前会话",
"tags": [
"Identity"
],
"x-owner-module": "Identity",
"x-required-scope": "authenticated",
"parameters": [],
"responses": {
"204": {
"description": "撤销当前会话",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/me": {
"get": {
"operationId": "me",
"summary": "读取本人身份与权限",
"tags": [
"Identity"
],
"x-owner-module": "Identity",
"x-required-scope": "authenticated",
"parameters": [],
"responses": {
"200": {
"description": "读取本人身份与权限",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Me"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/capabilities": {
"get": {
"operationId": "capabilities",
"summary": "获取当前用户可见能力",
"tags": [
"Agent"
],
"x-owner-module": "Agent",
"x-required-scope": "authenticated",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
],
"responses": {
"200": {
"description": "获取当前用户可见能力",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CapabilityPage"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/workspaces": {
"get": {
"operationId": "listWorkspaces",
"summary": "列出本人的事项",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:read",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
],
"responses": {
"200": {
"description": "列出本人的事项",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspacePage"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"operationId": "createWorkspace",
"summary": "建立个人事项",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:write",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"description": "按 tenant/user/workspace/operation 作用域持久去重;不同输入复用同键返回409。上传哈希含实际文件sha256。"
}
],
"responses": {
"201": {
"description": "建立个人事项",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
},
"Location": {
"schema": {
"type": "string"
},
"description": "已创建资源/任务查询地址"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Workspace"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceCreate"
}
}
}
}
}
},
"/api/v1/workspaces/{workspace_id}": {
"get": {
"operationId": "getWorkspace",
"summary": "进入事项",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:read",
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "进入事项",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Workspace"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"patch": {
"operationId": "renameWorkspace",
"summary": "按版本重命名事项",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:write",
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "按版本重命名事项",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Workspace"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspacePatch"
}
}
}
}
}
},
"/api/v1/workspaces/{workspace_id}/messages": {
"get": {
"operationId": "listMessages",
"summary": "读取对话历史",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:read",
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
],
"responses": {
"200": {
"description": "读取对话历史",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessagePage"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"operationId": "createMessage",
"summary": "追加用户消息",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:write",
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"description": "按 tenant/user/workspace/operation 作用域持久去重;不同输入复用同键返回409。上传哈希含实际文件sha256。"
}
],
"responses": {
"201": {
"description": "追加用户消息",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
},
"Location": {
"schema": {
"type": "string"
},
"description": "已创建资源/任务查询地址"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Message"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MessageCreate"
}
}
}
}
}
},
"/api/v1/workspaces/{workspace_id}/attachments": {
"get": {
"operationId": "listAttachments",
"summary": "列出事项附件",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:read",
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
],
"responses": {
"200": {
"description": "列出事项附件",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AttachmentPage"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"operationId": "uploadAttachment",
"summary": "上传一个附件并安排解析",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:write",
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"description": "按 tenant/user/workspace/operation 作用域持久去重;不同输入复用同键返回409。上传哈希含实际文件sha256。"
}
],
"responses": {
"201": {
"description": "上传一个附件并安排解析",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
},
"Location": {
"schema": {
"type": "string"
},
"description": "已创建资源/任务查询地址"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Attachment"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "单文件≤10MiB;实际流量计数,支持pdf/docx/txt/md"
}
},
"required": [
"file"
],
"additionalProperties": false
}
}
}
}
}
},
"/api/v1/attachments/{attachment_id}/content": {
"get": {
"operationId": "downloadAttachment",
"summary": "授权下载附件",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:read",
"parameters": [
{
"name": "attachment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "授权下载附件",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
},
"Content-Disposition": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"description": "经净化的下载文件名"
}
},
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/workspaces/{workspace_id}/context": {
"get": {
"operationId": "readContextSummary",
"summary": "读取授权事实与来源摘要",
"tags": [
"Context"
],
"x-owner-module": "Context",
"x-required-scope": "workspace:read",
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "读取授权事实与来源摘要",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContextSummary"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/knowledge-bases": {
"get": {
"operationId": "listKnowledgeBases",
"summary": "列出授权知识库",
"tags": [
"Knowledge"
],
"x-owner-module": "Knowledge",
"x-required-scope": "knowledge:read",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
],
"responses": {
"200": {
"description": "列出授权知识库",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeBasePage"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/knowledge/search": {
"post": {
"operationId": "searchKnowledge",
"summary": "授权范围内检索",
"tags": [
"Knowledge"
],
"x-owner-module": "Knowledge",
"x-required-scope": "knowledge:read",
"parameters": [],
"responses": {
"200": {
"description": "授权范围内检索",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CitationPage"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchInput"
}
}
}
}
}
},
"/api/v1/citations/{citation_id}": {
"get": {
"operationId": "getCitation",
"summary": "查看授权原文定位片段",
"tags": [
"Knowledge"
],
"x-owner-module": "Knowledge",
"x-required-scope": "knowledge:read",
"parameters": [
{
"name": "citation_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "查看授权原文定位片段",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Citation"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/employees": {
"get": {
"operationId": "listEmployees",
"summary": "数字员工目录",
"tags": [
"Agent"
],
"x-owner-module": "Agent",
"x-required-scope": "authenticated",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
],
"responses": {
"200": {
"description": "数字员工目录",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmployeePage"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/skills": {
"get": {
"operationId": "listSkills",
"summary": "个人及共享技能目录",
"tags": [
"Agent"
],
"x-owner-module": "Agent",
"x-required-scope": "authenticated",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
],
"responses": {
"200": {
"description": "个人及共享技能目录",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillPage"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"operationId": "createSkill",
"summary": "保存个人 Skill",
"tags": [
"Agent"
],
"x-owner-module": "Agent",
"x-required-scope": "skill:write",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"description": "按 tenant/user/workspace/operation 作用域持久去重;不同输入复用同键返回409。上传哈希含实际文件sha256。"
}
],
"responses": {
"201": {
"description": "保存个人 Skill",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
},
"Location": {
"schema": {
"type": "string"
},
"description": "已创建资源/任务查询地址"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Skill"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillCreate"
}
}
}
}
}
},
"/api/v1/skills/{skill_id}": {
"put": {
"operationId": "updateSkill",
"summary": "按版本更新个人 Skill",
"tags": [
"Agent"
],
"x-owner-module": "Agent",
"x-required-scope": "skill:write",
"parameters": [
{
"name": "skill_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "按版本更新个人 Skill",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Skill"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SkillUpdate"
}
}
}
}
}
},
"/api/v1/workspaces/{workspace_id}/skills": {
"put": {
"operationId": "bindWorkspaceSkills",
"summary": "按版本更新事项技能选项",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:write",
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "按版本更新事项技能选项",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceSkills"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WorkspaceSkillsInput"
}
}
}
}
}
},
"/api/v1/workspaces/{workspace_id}/runs": {
"post": {
"operationId": "startRun",
"summary": "调用数字员工并注入技能",
"tags": [
"Agent"
],
"x-owner-module": "Agent",
"x-required-scope": "run:write",
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"description": "按 tenant/user/workspace/operation 作用域持久去重;不同输入复用同键返回409。上传哈希含实际文件sha256。"
}
],
"responses": {
"202": {
"description": "调用数字员工并注入技能",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
},
"Location": {
"schema": {
"type": "string"
},
"description": "已创建资源/任务查询地址"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Run"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StartRun"
}
}
}
}
}
},
"/api/v1/runs/{run_id}": {
"get": {
"operationId": "getRun",
"summary": "任务快照与游标",
"tags": [
"Agent"
],
"x-owner-module": "Agent",
"x-required-scope": "run:read",
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "任务快照与游标",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Run"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/runs/{run_id}/events": {
"get": {
"operationId": "subscribeRunEvents",
"summary": "授权进度流与续读",
"tags": [
"Agent"
],
"x-owner-module": "Agent",
"x-required-scope": "run:read",
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"name": "Last-Event-ID",
"in": "header",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"description": "run_id:sequence;优先于after_sequence"
},
{
"name": "after_sequence",
"in": "query",
"schema": {
"type": "integer",
"minimum": 0
},
"description": "首次手工续读游标"
}
],
"responses": {
"410": {
"description": "EVENTS_EXPIRED:获取run快照后从last_sequence恢复",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"200": {
"description": "授权进度流与续读",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"text/event-stream": {
"schema": {
"type": "string"
},
"example": "id: run_001:1\nevent: run.queued\ndata: {\"event_id\":\"evt_001\",\"event_type\":\"run.queued\",\"event_version\":1,\"tenant_id\":\"demo\",\"owner_user_id\":\"demo_a\",\"workspace_id\":\"ws_001\",\"run_id\":\"run_001\",\"sequence\":1,\"trace_id\":\"tr_001\",\"occurred_at\":\"2026-10-10T02:00:00Z\",\"payload\":{\"status\":\"queued\"}}\n\n"
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-event-data-schema": {
"$ref": "#/components/schemas/RunEventEnvelope"
}
}
},
"/api/v1/runs/{run_id}/cancel": {
"post": {
"operationId": "cancelRun",
"summary": "请求在安全边界取消",
"tags": [
"Agent"
],
"x-owner-module": "Agent",
"x-required-scope": "run:write",
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"description": "按 tenant/user/workspace/operation 作用域持久去重;不同输入复用同键返回409。上传哈希含实际文件sha256。"
}
],
"responses": {
"202": {
"description": "请求在安全边界取消",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
},
"Location": {
"schema": {
"type": "string"
},
"description": "已创建资源/任务查询地址"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Run"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/runs/{run_id}/approval": {
"post": {
"operationId": "approveRun",
"summary": "批准指定草稿版本并续跑",
"tags": [
"Agent"
],
"x-owner-module": "Agent",
"x-required-scope": "run:approve",
"parameters": [
{
"name": "run_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"description": "按 tenant/user/workspace/operation 作用域持久去重;不同输入复用同键返回409。上传哈希含实际文件sha256。"
}
],
"responses": {
"202": {
"description": "批准指定草稿版本并续跑",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
},
"Location": {
"schema": {
"type": "string"
},
"description": "已创建资源/任务查询地址"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Run"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApprovalInput"
}
}
}
}
}
},
"/api/v1/artifacts/{artifact_id}": {
"get": {
"operationId": "getArtifact",
"summary": "读取本人草稿当前版本",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:read",
"parameters": [
{
"name": "artifact_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "读取本人草稿当前版本",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Artifact"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"patch": {
"operationId": "editArtifact",
"summary": "乐观锁修改草稿",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:write",
"parameters": [
{
"name": "artifact_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "乐观锁修改草稿",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Artifact"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ArtifactPatch"
}
}
}
}
}
},
"/api/v1/artifacts/{artifact_id}/versions/{version}/content": {
"get": {
"operationId": "downloadArtifact",
"summary": "下载已生成的版本文件",
"tags": [
"Workspace"
],
"x-owner-module": "Workspace",
"x-required-scope": "workspace:read",
"parameters": [
{
"name": "artifact_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"name": "version",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 1
}
}
],
"responses": {
"200": {
"description": "下载已生成的版本文件",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
},
"Content-Disposition": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"description": "经净化的下载文件名"
}
},
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/tools": {
"get": {
"operationId": "listTools",
"summary": "查看允许的工具能力",
"tags": [
"Tool"
],
"x-owner-module": "Tool",
"x-required-scope": "authenticated",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
],
"responses": {
"200": {
"description": "查看允许的工具能力",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolCapabilityPage"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/tool-receipts/{receipt_id}": {
"get": {
"operationId": "getToolReceipt",
"summary": "读取本人工具回执",
"tags": [
"Tool"
],
"x-owner-module": "Tool",
"x-required-scope": "workspace:read",
"parameters": [
{
"name": "receipt_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "读取本人工具回执",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolReceipt"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/notifications": {
"get": {
"operationId": "listNotifications",
"summary": "本人通知与投递结果",
"tags": [
"Notification"
],
"x-owner-module": "Notification",
"x-required-scope": "authenticated",
"parameters": [
{
"name": "limit",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 20
}
},
{
"name": "cursor",
"in": "query",
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 1024
}
}
],
"responses": {
"200": {
"description": "本人通知与投递结果",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotificationPage"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/notifications/{notification_id}/read": {
"post": {
"operationId": "markNotificationRead",
"summary": "标记本人通知已读",
"tags": [
"Notification"
],
"x-owner-module": "Notification",
"x-required-scope": "authenticated",
"parameters": [
{
"name": "notification_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
],
"responses": {
"200": {
"description": "标记本人通知已读",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Notification"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/health/live": {
"get": {
"operationId": "liveness",
"summary": "进程存活",
"tags": [
"Gateway"
],
"x-owner-module": "Gateway",
"x-required-scope": "public",
"parameters": [],
"responses": {
"200": {
"description": "进程存活",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Liveness"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"security": []
}
},
"/health/ready": {
"get": {
"operationId": "readiness",
"summary": "诊断模块就绪与运行模式",
"tags": [
"Gateway"
],
"x-owner-module": "Gateway",
"x-required-scope": "ops:read",
"parameters": [],
"responses": {
"200": {
"description": "诊断模块就绪与运行模式",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Readiness"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "配置或强依赖未就绪",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Readiness"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v1/workspaces/{workspace_id}/chat": {
"post": {
"operationId": "directChat",
"summary": "不选数字员工时直接模型对话并保存双向消息",
"tags": [
"LLM",
"Workspace"
],
"x-owner-module": "LLM",
"x-required-scope": "workspace:write",
"parameters": [
{
"name": "workspace_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128
},
"description": "按 tenant/user/workspace/operation 作用域持久去重;不同输入复用同键返回409。上传哈希含实际文件sha256。"
}
],
"responses": {
"201": {
"description": "模型演示桩回复与双向持久化消息",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectChatResponse"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"413": {
"description": "PAYLOAD_TOO_LARGE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"415": {
"description": "UNSUPPORTED_MEDIA_TYPE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "VALIDATION_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "RATE_LIMITED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
},
"description": "建议等待的秒数"
}
}
},
"500": {
"description": "INTERNAL_ERROR",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"502": {
"description": "UPSTREAM_BAD_RESPONSE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"503": {
"description": "DEPENDENCY_UNAVAILABLE",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"504": {
"description": "UPSTREAM_TIMEOUT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectChatInput"
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"schemas": {
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"trace_id": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"details": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"code",
"message",
"trace_id",
"details"
],
"additionalProperties": false
},
"LoginInput": {
"type": "object",
"properties": {
"username": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"password": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"writeOnly": true
}
},
"required": [
"username",
"password"
],
"additionalProperties": false
},
"Token": {
"type": "object",
"properties": {
"access_token": {
"type": "string",
"minLength": 1,
"maxLength": 8192
},
"token_type": {
"type": "string",
"const": "Bearer"
},
"expires_in": {
"type": "integer",
"minimum": 1
},
"auth_mode": {
"type": "string",
"enum": [
"demo",
"oidc"
]
}
},
"required": [
"access_token",
"token_type",
"expires_in",
"auth_mode"
],
"additionalProperties": false
},
"Me": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"tenant_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"display_name": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"scopes": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
}
},
"required": [
"user_id",
"tenant_id",
"display_name",
"scopes"
],
"additionalProperties": false
},
"Capability": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"enabled": {
"type": "boolean"
},
"reason": {
"type": "string",
"maxLength": 300
}
},
"required": [
"id",
"enabled",
"reason"
],
"additionalProperties": false
},
"WorkspaceCreate": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"required": [
"title"
],
"additionalProperties": false
},
"WorkspacePatch": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"expected_version": {
"type": "integer",
"minimum": 1
}
},
"required": [
"title",
"expected_version"
],
"additionalProperties": false
},
"Workspace": {
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"parent_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"version": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string",
"minLength": 1,
"maxLength": 32
},
"latest_artifact_id": {
"type": [
"string",
"null"
],
"description": "当前事项最新草稿 ID;为空表示尚无草稿"
}
},
"required": [
"workspace_id",
"parent_id",
"title",
"version",
"status"
],
"additionalProperties": false
},
"MessageCreate": {
"type": "object",
"properties": {
"content": {
"type": "string",
"minLength": 1,
"maxLength": 8192
}
},
"required": [
"content"
],
"additionalProperties": false
},
"Message": {
"type": "object",
"properties": {
"message_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"workspace_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"role": {
"type": "string",
"enum": [
"user",
"assistant"
]
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 32768
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"message_id",
"workspace_id",
"role",
"content",
"created_at"
],
"additionalProperties": false
},
"Attachment": {
"type": "object",
"properties": {
"attachment_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"workspace_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"bytes": {
"type": "integer",
"minimum": 0,
"maximum": 10485760
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"parse_status": {
"type": "string",
"enum": [
"uploaded",
"parsing",
"ready",
"failed"
]
}
},
"required": [
"attachment_id",
"workspace_id",
"filename",
"bytes",
"sha256",
"parse_status"
],
"additionalProperties": false
},
"ContextSummary": {
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"confirmed_facts": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"source_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"snapshot_version": {
"type": "integer",
"minimum": 1
}
},
"required": [
"workspace_id",
"confirmed_facts",
"source_ids",
"snapshot_version"
],
"additionalProperties": false
},
"KnowledgeBase": {
"type": "object",
"properties": {
"base_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"access": {
"type": "string",
"enum": [
"read",
"manage"
]
}
},
"required": [
"base_id",
"name",
"access"
],
"additionalProperties": false
},
"SearchInput": {
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"base_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"top_k": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"default": 5
}
},
"required": [
"workspace_id",
"query"
],
"additionalProperties": false
},
"Citation": {
"type": "object",
"properties": {
"citation_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"document_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"document_version": {
"type": "integer",
"minimum": 1
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"locator": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"snippet": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
},
"required": [
"citation_id",
"document_id",
"document_version",
"title",
"locator",
"snippet"
],
"additionalProperties": false
},
"Employee": {
"type": "object",
"properties": {
"employee_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"enabled": {
"type": "boolean"
},
"workflow_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"workflow_version": {
"type": "integer",
"minimum": 1
},
"default_skill_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
},
"required": [
"employee_id",
"name",
"enabled",
"workflow_id",
"workflow_version",
"default_skill_ids"
],
"additionalProperties": false
},
"SkillCreate": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"category": {
"type": "string",
"enum": [
"document",
"knowledge"
]
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 32768,
"x-max-utf8-bytes": 32768,
"description": "声明式Skill文本;maxLength限制字符,服务端另检查UTF-8编码字节数不超过32768。不得由内容提升工具权限。"
}
},
"required": [
"name",
"category",
"content"
],
"additionalProperties": false
},
"SkillUpdate": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"category": {
"type": "string",
"enum": [
"document",
"knowledge"
]
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 32768,
"x-max-utf8-bytes": 32768,
"description": "声明式Skill文本;maxLength限制字符,服务端另检查UTF-8编码字节数不超过32768。不得由内容提升工具权限。"
},
"expected_version": {
"type": "integer",
"minimum": 1
}
},
"required": [
"name",
"category",
"content",
"expected_version"
],
"additionalProperties": false
},
"Skill": {
"type": "object",
"properties": {
"skill_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"category": {
"type": "string",
"enum": [
"document",
"knowledge"
]
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 32768,
"x-max-utf8-bytes": 32768,
"description": "声明式Skill文本;maxLength限制字符,服务端另检查UTF-8编码字节数不超过32768。不得由内容提升工具权限。"
},
"version": {
"type": "integer",
"minimum": 1
},
"content_hash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"owner_scope": {
"type": "string",
"enum": [
"personal",
"shared"
]
}
},
"required": [
"skill_id",
"name",
"category",
"content",
"version",
"content_hash",
"owner_scope"
],
"additionalProperties": false
},
"SkillSnapshot": {
"type": "object",
"properties": {
"skill_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"version": {
"type": "integer",
"minimum": 1
},
"content_hash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"skill_id",
"version",
"content_hash"
],
"additionalProperties": false
},
"WorkspaceSkillsInput": {
"type": "object",
"properties": {
"skill_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"expected_version": {
"type": "integer",
"minimum": 1
}
},
"required": [
"skill_ids",
"expected_version"
],
"additionalProperties": false
},
"WorkspaceSkills": {
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"skill_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
},
"version": {
"type": "integer",
"minimum": 1
}
},
"required": [
"workspace_id",
"skill_ids",
"version"
],
"additionalProperties": false
},
"StartRun": {
"type": "object",
"properties": {
"employee_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"input_message_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"skill_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
},
"required": [
"employee_id",
"input_message_id"
],
"additionalProperties": false
},
"Run": {
"type": "object",
"properties": {
"run_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"workspace_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"status": {
"type": "string",
"enum": [
"queued",
"running",
"awaiting_confirmation",
"waiting_device",
"succeeded",
"failed",
"cancelled"
]
},
"last_sequence": {
"type": "integer",
"minimum": 0
},
"mode": {
"type": "string",
"enum": [
"real",
"fixture"
]
},
"workflow_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"workflow_version": {
"type": "integer",
"minimum": 1
},
"effective_skills": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SkillSnapshot"
}
},
"artifact_id": {
"type": [
"string",
"null"
]
}
},
"required": [
"run_id",
"workspace_id",
"status",
"last_sequence",
"mode",
"workflow_id",
"workflow_version",
"effective_skills"
],
"additionalProperties": false
},
"ApprovalInput": {
"type": "object",
"properties": {
"artifact_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"expected_version": {
"type": "integer",
"minimum": 1
},
"content_hash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"artifact_id",
"expected_version",
"content_hash"
],
"additionalProperties": false
},
"ArtifactPatch": {
"type": "object",
"properties": {
"content": {
"type": "string",
"minLength": 1,
"maxLength": 65536
},
"expected_version": {
"type": "integer",
"minimum": 1
}
},
"required": [
"content",
"expected_version"
],
"additionalProperties": false
},
"Artifact": {
"type": "object",
"properties": {
"artifact_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"workspace_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"version": {
"type": "integer",
"minimum": 1
},
"content": {
"type": "string",
"minLength": 1,
"maxLength": 65536
},
"content_hash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"approval_status": {
"type": "string",
"enum": [
"unconfirmed",
"approved"
]
},
"citation_ids": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 256
}
}
},
"required": [
"artifact_id",
"workspace_id",
"version",
"content",
"content_hash",
"approval_status",
"citation_ids"
],
"additionalProperties": false
},
"ToolCapability": {
"type": "object",
"properties": {
"tool_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"execution_location": {
"type": "string",
"enum": [
"server",
"pc"
]
},
"requires_confirmation": {
"type": "boolean"
}
},
"required": [
"tool_id",
"name",
"execution_location",
"requires_confirmation"
],
"additionalProperties": false
},
"ToolReceipt": {
"type": "object",
"properties": {
"receipt_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"run_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"artifact_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"artifact_version": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed",
"unknown",
"waiting_device"
]
},
"execution_location": {
"type": "string",
"enum": [
"server",
"pc"
]
}
},
"required": [
"receipt_id",
"run_id",
"artifact_id",
"artifact_version",
"status",
"execution_location"
],
"additionalProperties": false
},
"Notification": {
"type": "object",
"properties": {
"notification_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"run_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"read": {
"type": "boolean"
},
"delivery_status": {
"type": "string",
"enum": [
"pending",
"sent",
"failed",
"unknown"
]
},
"provider_mode": {
"type": "string",
"enum": [
"real",
"demo"
]
}
},
"required": [
"notification_id",
"run_id",
"title",
"read",
"delivery_status",
"provider_mode"
],
"additionalProperties": false
},
"Liveness": {
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "alive"
}
},
"required": [
"status"
],
"additionalProperties": false
},
"DependencyState": {
"type": "object",
"properties": {
"module_id": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"status": {
"type": "string",
"enum": [
"ready",
"not_ready",
"degraded",
"disabled"
]
},
"mode": {
"type": "string",
"minLength": 1,
"maxLength": 32
}
},
"required": [
"module_id",
"status",
"mode"
],
"additionalProperties": false
},
"Readiness": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"ready",
"not_ready",
"degraded"
]
},
"config_revision": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"dependencies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DependencyState"
}
}
},
"required": [
"status",
"config_revision",
"dependencies"
],
"additionalProperties": false
},
"RunEventEnvelope": {
"title": "RunEventEnvelope",
"type": "object",
"required": [
"event_id",
"event_type",
"event_version",
"tenant_id",
"owner_user_id",
"workspace_id",
"run_id",
"sequence",
"trace_id",
"occurred_at",
"payload"
],
"properties": {
"event_id": {
"type": "string"
},
"event_type": {
"type": "string"
},
"tenant_id": {
"type": "string"
},
"owner_user_id": {
"type": "string"
},
"workspace_id": {
"type": "string"
},
"run_id": {
"type": "string"
},
"step_id": {
"type": "string"
},
"trace_id": {
"type": "string"
},
"occurred_at": {
"type": "string"
},
"event_version": {
"type": "integer",
"minimum": 1
},
"sequence": {
"type": "integer",
"minimum": 1
},
"payload": {
"type": "object"
}
},
"additionalProperties": false
},
"CapabilityPage": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Capability"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"additionalProperties": false
},
"WorkspacePage": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Workspace"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"additionalProperties": false
},
"MessagePage": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Message"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"additionalProperties": false
},
"AttachmentPage": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Attachment"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"additionalProperties": false
},
"KnowledgeBasePage": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/KnowledgeBase"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"additionalProperties": false
},
"CitationPage": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Citation"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"additionalProperties": false
},
"EmployeePage": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Employee"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"additionalProperties": false
},
"SkillPage": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Skill"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"additionalProperties": false
},
"ToolCapabilityPage": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ToolCapability"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"additionalProperties": false
},
"NotificationPage": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Notification"
}
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor"
],
"additionalProperties": false
},
"DirectChatInput": {
"type": "object",
"properties": {
"content": {
"type": "string",
"minLength": 1,
"maxLength": 8192
}
},
"required": [
"content"
],
"additionalProperties": false
},
"DirectChatResponse": {
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"user_message": {
"$ref": "#/components/schemas/Message"
},
"assistant_message": {
"$ref": "#/components/schemas/Message"
},
"mode": {
"type": "string",
"enum": [
"fixture",
"live"
]
},
"model_id": {
"type": "string"
}
},
"required": [
"workspace_id",
"user_message",
"assistant_message",
"mode",
"model_id"
],
"additionalProperties": false
}
}
}
}
{
"openapi": "3.1.0",
"info": {
"title": "Work OS API Gateway PC design contract",
"version": "1.0.0",
"description": "PC 37 项设计契约;Gateway 已有演示实现,Workspace 已接持久化首版,其它下游服务仍为 fixture。"
},
"servers": [
{
"url": "http://127.0.0.1:8000",
"description": "PC loopback design target"
}
],
"security": [
{
"BearerAuth": []
}
],
"paths": {
"/api/v1/auth/login": {
"post": {
"operationId": "login",
"summary": "演示账号登录",
"tags": [
"Identity"
],
"x-owner-module": "Identity",
"x-required-scope": "public",
"parameters": [],
"responses": {
"200": {
"description": "演示账号登录",
"headers": {
"X-Trace-Id": {
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"description": "服务器生成的请求跟踪ID"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Token"
}
}
}
},
"400": {
"description": "INVALID_REQUEST",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "TOKEN_INVALID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "SCOPE_DENIED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "RESOURCE_NOT_FOUND",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "VERSION_CONFLICT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},