dellweb3's picture
Work OS validated demo local-v0.8
99caad5 verified
Raw History Blame Contribute Delete
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"
}
}
}
},