1010 lines
32 KiB
YAML
1010 lines
32 KiB
YAML
openapi: 3.0.3
|
||
info:
|
||
title: Agents API v1
|
||
version: "1.0"
|
||
description: |
|
||
多工作区 + 后台任务 + HTTP 轮询进度 + 文件上传/下载。
|
||
|
||
- 鉴权：Authorization: Bearer <token>（token 为自定义字符串，服务端存 SHA256）
|
||
- 事件流：与网页端 WebSocket 同粒度（text_chunk、tool_start 等）
|
||
- 多工作区：所有对话/消息/文件都在指定 workspace 下进行
|
||
servers:
|
||
- url: http://localhost:8091
|
||
|
||
components:
|
||
securitySchemes:
|
||
bearerAuth:
|
||
type: http
|
||
scheme: bearer
|
||
bearerFormat: token
|
||
schemas:
|
||
ErrorResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: false }
|
||
error: { type: string, example: "无效的 Token" }
|
||
required: [success, error]
|
||
|
||
CreateConversationRequest:
|
||
type: object
|
||
description: 可选参数；用于在创建对话时绑定 prompt/personalization
|
||
properties:
|
||
prompt_name:
|
||
type: string
|
||
nullable: true
|
||
description: 自定义主 prompt 名称（用户级共享，shared/prompts/<name>.txt）
|
||
personalization_name:
|
||
type: string
|
||
nullable: true
|
||
description: 个性化配置名称（用户级共享，shared/personalization/<name>.json）
|
||
additionalProperties: false
|
||
|
||
CreateConversationResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
workspace_id: { type: string, example: "ws1" }
|
||
conversation_id: { type: string, example: "conv_20260123_234245_036" }
|
||
required: [success, workspace_id, conversation_id]
|
||
|
||
SendMessageRequest:
|
||
type: object
|
||
properties:
|
||
message:
|
||
type: string
|
||
description: 用户消息文本（message 与 images 至少其一不为空）
|
||
images:
|
||
type: array
|
||
items: { type: string }
|
||
description: 图片路径列表（相对 project 根目录）
|
||
conversation_id:
|
||
type: string
|
||
description: 对话 ID；不传则自动创建
|
||
model_key:
|
||
type: string
|
||
nullable: true
|
||
description: 模型 key（可选，取决于服务端配置）
|
||
run_mode:
|
||
type: string
|
||
nullable: true
|
||
description: 运行模式：fast | thinking | deep；若传入则优先使用
|
||
thinking_mode:
|
||
type: boolean
|
||
nullable: true
|
||
description: 是否开启思考模式（true/false）
|
||
max_iterations:
|
||
type: integer
|
||
nullable: true
|
||
description: 最大迭代次数（最多允许多少轮模型调用/工具循环）
|
||
prompt_name:
|
||
type: string
|
||
nullable: true
|
||
description: 自定义主 prompt 名称（用户级共享，shared/prompts/<name>.txt）
|
||
personalization_name:
|
||
type: string
|
||
nullable: true
|
||
description: 个性化配置名称（用户级共享，shared/personalization/<name>.json）
|
||
additionalProperties: false
|
||
|
||
PersonalizationConfig:
|
||
type: object
|
||
description: 个性化配置结构（content），服务端会规范化与回落默认值
|
||
properties:
|
||
enabled: { type: boolean, default: false }
|
||
self_identify: { type: string, default: "" }
|
||
user_name: { type: string, default: "" }
|
||
profession: { type: string, default: "" }
|
||
tone: { type: string, default: "" }
|
||
considerations:
|
||
type: array
|
||
items: { type: string }
|
||
default: []
|
||
description: 最多 10 条，每条最多 50 字符
|
||
thinking_interval:
|
||
type: integer
|
||
nullable: true
|
||
description: 1~50；非法值会被置空
|
||
disabled_tool_categories:
|
||
type: array
|
||
items: { type: string }
|
||
default: []
|
||
default_run_mode:
|
||
type: string
|
||
nullable: true
|
||
description: fast/thinking/deep 或 null
|
||
auto_generate_title: { type: boolean, default: true }
|
||
tool_intent_enabled: { type: boolean, default: true }
|
||
default_model:
|
||
type: string
|
||
default: kimi
|
||
description: kimi/deepseek/qwen3-max/qwen3-vl-plus
|
||
additionalProperties: true
|
||
example:
|
||
enabled: true
|
||
user_name: "Jojo"
|
||
tone: "企业商务"
|
||
considerations: ["优先给出结论，再补充依据"]
|
||
|
||
PromptUpsertRequest:
|
||
type: object
|
||
properties:
|
||
name: { type: string, example: "prompt_strict" }
|
||
content: { type: string, example: "严格模式：..." }
|
||
required: [name, content]
|
||
additionalProperties: false
|
||
|
||
PromptGetResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
name: { type: string, example: "prompt_strict" }
|
||
content: { type: string, example: "严格模式：..." }
|
||
required: [success, name, content]
|
||
|
||
PromptListItem:
|
||
type: object
|
||
properties:
|
||
name: { type: string, example: "prompt_strict" }
|
||
size: { type: integer, example: 123 }
|
||
updated_at: { type: number, format: double, example: 1769182550.59 }
|
||
required: [name, size, updated_at]
|
||
|
||
PromptListResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
items:
|
||
type: array
|
||
items: { $ref: "#/components/schemas/PromptListItem" }
|
||
required: [success, items]
|
||
|
||
PersonalizationUpsertRequest:
|
||
type: object
|
||
properties:
|
||
name: { type: string, example: "biz_mobile" }
|
||
content: { $ref: "#/components/schemas/PersonalizationConfig" }
|
||
required: [name, content]
|
||
additionalProperties: false
|
||
|
||
PersonalizationGetResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
name: { type: string, example: "biz_mobile" }
|
||
content: { $ref: "#/components/schemas/PersonalizationConfig" }
|
||
required: [success, name, content]
|
||
|
||
PersonalizationListItem:
|
||
type: object
|
||
properties:
|
||
name: { type: string, example: "biz_mobile" }
|
||
size: { type: integer, example: 345 }
|
||
updated_at: { type: number, format: double, example: 1769182550.59 }
|
||
required: [name, size, updated_at]
|
||
|
||
PersonalizationListResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
items:
|
||
type: array
|
||
items: { $ref: "#/components/schemas/PersonalizationListItem" }
|
||
required: [success, items]
|
||
|
||
ConversationListItem:
|
||
type: object
|
||
properties:
|
||
workspace_id: { type: string, example: "ws1" }
|
||
id: { type: string, example: "conv_20260124_023218_677" }
|
||
title: { type: string, example: "新对话" }
|
||
created_at: { type: string, example: "2026-01-24T02:32:18.677Z" }
|
||
updated_at: { type: string, example: "2026-01-24T02:33:10.123Z" }
|
||
run_mode: { type: string, nullable: true, example: "fast" }
|
||
model_key: { type: string, nullable: true, example: "kimi" }
|
||
custom_prompt_name: { type: string, nullable: true, example: "custom_a" }
|
||
personalization_name: { type: string, nullable: true, example: "biz_mobile" }
|
||
messages_count: { type: integer, example: 6 }
|
||
required: [workspace_id, id, title, created_at, updated_at, messages_count]
|
||
|
||
ConversationListResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
data:
|
||
type: array
|
||
items: { $ref: "#/components/schemas/ConversationListItem" }
|
||
total: { type: integer, example: 42 }
|
||
required: [success, data, total]
|
||
|
||
ConversationGetResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
workspace_id: { type: string, example: "ws1" }
|
||
data:
|
||
type: object
|
||
additionalProperties: true
|
||
required: [success, workspace_id, data]
|
||
|
||
DeleteConversationResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
workspace_id: { type: string, example: "ws1" }
|
||
message: { type: string, example: "对话已删除: conv_..." }
|
||
required: [success, workspace_id, message]
|
||
|
||
ModelsResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
items:
|
||
type: array
|
||
items:
|
||
type: object
|
||
properties:
|
||
model_key: { type: string, example: "kimi" }
|
||
name: { type: string, example: "Kimi" }
|
||
supports_thinking: { type: boolean, example: true }
|
||
fast_only: { type: boolean, example: false }
|
||
required: [model_key, name, supports_thinking, fast_only]
|
||
required: [success, items]
|
||
|
||
HealthResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
status: { type: string, example: "ok" }
|
||
required: [success, status]
|
||
|
||
SendMessageResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
task_id: { type: string, example: "60322db3-f884-4a1e-a9b3-6eeb07fbab47" }
|
||
conversation_id: { type: string, example: "conv_20260123_234245_036" }
|
||
workspace_id: { type: string, example: "ws1" }
|
||
status: { type: string, example: "running" }
|
||
created_at: { type: number, format: double, example: 1769182965.3038778 }
|
||
required: [success, task_id, conversation_id, workspace_id, status, created_at]
|
||
|
||
TaskEvent:
|
||
type: object
|
||
properties:
|
||
idx: { type: integer, example: 12 }
|
||
type: { type: string, example: "text_chunk" }
|
||
data:
|
||
type: object
|
||
additionalProperties: true
|
||
ts: { type: number, format: double, example: 1769182968.154797 }
|
||
required: [idx, type, data, ts]
|
||
|
||
TaskPollResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
data:
|
||
type: object
|
||
properties:
|
||
task_id: { type: string }
|
||
workspace_id: { type: string, nullable: true }
|
||
status: { type: string, example: "running" }
|
||
created_at: { type: number, format: double }
|
||
updated_at: { type: number, format: double }
|
||
error: { type: string, nullable: true }
|
||
events:
|
||
type: array
|
||
items: { $ref: "#/components/schemas/TaskEvent" }
|
||
next_offset: { type: integer, example: 3 }
|
||
required: [task_id, status, created_at, updated_at, error, events, next_offset]
|
||
required: [success, data]
|
||
|
||
CancelResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
required: [success]
|
||
|
||
UploadResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
workspace_id: { type: string, example: "ws1" }
|
||
path: { type: string, example: "inputs/hello.txt" }
|
||
filename: { type: string, example: "hello.txt" }
|
||
size: { type: integer, example: 16 }
|
||
sha256: { type: string, example: "0f5bd6..." }
|
||
required: [success, workspace_id, path, filename]
|
||
|
||
ListFilesItem:
|
||
type: object
|
||
properties:
|
||
name: { type: string, example: "hello.txt" }
|
||
is_dir: { type: boolean, example: false }
|
||
size: { type: integer, example: 16 }
|
||
modified_at: { type: number, format: double, example: 1769182550.594278 }
|
||
path: { type: string, example: "inputs/hello.txt" }
|
||
required: [name, is_dir, size, modified_at, path]
|
||
|
||
ListFilesResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
workspace_id: { type: string, example: "ws1" }
|
||
base: { type: string, example: "." }
|
||
items:
|
||
type: array
|
||
items: { $ref: "#/components/schemas/ListFilesItem" }
|
||
required: [success, workspace_id, base, items]
|
||
|
||
WorkspaceCreateRequest:
|
||
type: object
|
||
properties:
|
||
workspace_id:
|
||
type: string
|
||
description: 仅允许字母/数字/._-，长度1-40
|
||
required: [workspace_id]
|
||
additionalProperties: false
|
||
|
||
WorkspaceInfo:
|
||
type: object
|
||
properties:
|
||
workspace_id: { type: string, example: "ws1" }
|
||
project_path: { type: string }
|
||
data_dir: { type: string }
|
||
has_conversations: { type: boolean }
|
||
required: [workspace_id, project_path, data_dir, has_conversations]
|
||
|
||
WorkspacesListResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
items:
|
||
type: array
|
||
items: { $ref: "#/components/schemas/WorkspaceInfo" }
|
||
required: [success, items]
|
||
|
||
WorkspaceCreateResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
workspace_id: { type: string, example: "ws1" }
|
||
project_path: { type: string }
|
||
data_dir: { type: string }
|
||
required: [success, workspace_id, project_path, data_dir]
|
||
|
||
ToolsCategory:
|
||
type: object
|
||
properties:
|
||
id: { type: string, example: "network" }
|
||
label: { type: string, example: "网络检索" }
|
||
default_enabled: { type: boolean, example: true }
|
||
silent_when_disabled: { type: boolean, example: false }
|
||
tools:
|
||
type: array
|
||
items: { type: string }
|
||
required: [id, label, default_enabled, silent_when_disabled, tools]
|
||
|
||
ToolsResponse:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
categories:
|
||
type: array
|
||
items: { $ref: "#/components/schemas/ToolsCategory" }
|
||
required: [success, categories]
|
||
|
||
security:
|
||
- bearerAuth: []
|
||
|
||
paths:
|
||
/api/v1/tools:
|
||
get:
|
||
summary: 获取工具分类与工具名称列表
|
||
security: [{ bearerAuth: [] }]
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ToolsResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/workspaces:
|
||
get:
|
||
summary: 列出工作区
|
||
security: [{ bearerAuth: [] }]
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/WorkspacesListResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
post:
|
||
summary: 创建/确保工作区存在
|
||
security: [{ bearerAuth: [] }]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/WorkspaceCreateRequest" }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/WorkspaceCreateResponse" }
|
||
"400":
|
||
description: Bad Request
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/workspaces/{workspace_id}:
|
||
get:
|
||
summary: 查询单个工作区
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: workspace_id
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
workspace: { $ref: "#/components/schemas/WorkspaceInfo" }
|
||
required: [success, workspace]
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
delete:
|
||
summary: 删除工作区（若有运行中任务则 409）
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: workspace_id
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
workspace_id: { type: string, example: "ws1" }
|
||
required: [success, workspace_id]
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"409":
|
||
description: Conflict (该工作区有运行中任务)
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/workspaces/{workspace_id}/conversations:
|
||
post:
|
||
summary: 创建对话（工作区内）
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: workspace_id
|
||
required: true
|
||
schema: { type: string }
|
||
requestBody:
|
||
required: false
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/CreateConversationRequest" }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/CreateConversationResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
get:
|
||
summary: 获取对话列表（工作区内）
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: workspace_id
|
||
required: true
|
||
schema: { type: string }
|
||
- in: query
|
||
name: limit
|
||
required: false
|
||
schema: { type: integer, default: 20, minimum: 1, maximum: 100 }
|
||
- in: query
|
||
name: offset
|
||
required: false
|
||
schema: { type: integer, default: 0, minimum: 0 }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ConversationListResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}:
|
||
get:
|
||
summary: 获取单个对话（工作区内，可选 full=1 返回 messages）
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: workspace_id
|
||
required: true
|
||
schema: { type: string }
|
||
- in: path
|
||
name: conversation_id
|
||
required: true
|
||
schema: { type: string }
|
||
- in: query
|
||
name: full
|
||
required: false
|
||
schema: { type: string, default: "0", enum: ["0", "1"] }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ConversationGetResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
delete:
|
||
summary: 删除对话（工作区内）
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: workspace_id
|
||
required: true
|
||
schema: { type: string }
|
||
- in: path
|
||
name: conversation_id
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/DeleteConversationResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/workspaces/{workspace_id}/messages:
|
||
post:
|
||
summary: 发送消息并创建后台任务（工作区内）
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: workspace_id
|
||
required: true
|
||
schema: { type: string }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/SendMessageRequest" }
|
||
responses:
|
||
"202":
|
||
description: Accepted
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/SendMessageResponse" }
|
||
"400":
|
||
description: Bad Request
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found (prompt/personalization 不存在)
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"409":
|
||
description: Conflict (该工作区已有运行任务)
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/prompts:
|
||
get:
|
||
summary: 列出 Prompt
|
||
security: [{ bearerAuth: [] }]
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/PromptListResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
post:
|
||
summary: 创建/覆盖 Prompt
|
||
security: [{ bearerAuth: [] }]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/PromptUpsertRequest" }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
success: { type: boolean, example: true }
|
||
name: { type: string, example: "prompt_strict" }
|
||
required: [success, name]
|
||
"400":
|
||
description: Bad Request
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/prompts/{name}:
|
||
get:
|
||
summary: 获取 Prompt 内容
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: name
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/PromptGetResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/personalizations:
|
||
get:
|
||
summary: 列出个性化配置
|
||
security: [{ bearerAuth: [] }]
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/PersonalizationListResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
post:
|
||
summary: 创建/覆盖个性化配置（服务端会 sanitize 并返回清洗后的 content）
|
||
security: [{ bearerAuth: [] }]
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/PersonalizationUpsertRequest" }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/PersonalizationGetResponse" }
|
||
"400":
|
||
description: Bad Request
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/personalizations/{name}:
|
||
get:
|
||
summary: 获取个性化配置内容（服务端会 sanitize 并可能回写）
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: name
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/PersonalizationGetResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/models:
|
||
get:
|
||
summary: 列出服务端模型（公开）
|
||
security: []
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ModelsResponse" }
|
||
|
||
/api/v1/health:
|
||
get:
|
||
summary: 健康检查（公开）
|
||
security: []
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/HealthResponse" }
|
||
|
||
/api/v1/tasks/{task_id}:
|
||
get:
|
||
summary: 轮询任务事件
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: task_id
|
||
required: true
|
||
schema: { type: string }
|
||
- in: query
|
||
name: from
|
||
required: false
|
||
schema: { type: integer, default: 0 }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/TaskPollResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/tasks/{task_id}/cancel:
|
||
post:
|
||
summary: 请求停止任务
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: task_id
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/CancelResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/workspaces/{workspace_id}/files/upload:
|
||
post:
|
||
summary: 上传文件到 user_upload
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: workspace_id
|
||
required: true
|
||
schema: { type: string }
|
||
requestBody:
|
||
required: true
|
||
content:
|
||
multipart/form-data:
|
||
schema:
|
||
type: object
|
||
properties:
|
||
file:
|
||
type: string
|
||
format: binary
|
||
filename:
|
||
type: string
|
||
dir:
|
||
type: string
|
||
description: user_upload 下子目录
|
||
required: [file]
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/UploadResponse" }
|
||
"400":
|
||
description: Bad Request
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/workspaces/{workspace_id}/files:
|
||
get:
|
||
summary: 列出 user_upload 目录内容
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: workspace_id
|
||
required: true
|
||
schema: { type: string }
|
||
- in: query
|
||
name: path
|
||
required: false
|
||
schema: { type: string, default: "" }
|
||
responses:
|
||
"200":
|
||
description: OK
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ListFilesResponse" }
|
||
"400":
|
||
description: Bad Request
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
|
||
/api/v1/workspaces/{workspace_id}/files/download:
|
||
get:
|
||
summary: 下载文件或目录（目录会打包成 zip）
|
||
security: [{ bearerAuth: [] }]
|
||
parameters:
|
||
- in: path
|
||
name: workspace_id
|
||
required: true
|
||
schema: { type: string }
|
||
- in: query
|
||
name: path
|
||
required: true
|
||
schema: { type: string }
|
||
responses:
|
||
"200":
|
||
description: File content
|
||
content:
|
||
application/octet-stream:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
application/zip:
|
||
schema:
|
||
type: string
|
||
format: binary
|
||
"400":
|
||
description: Bad Request
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"401":
|
||
description: Unauthorized
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|
||
"404":
|
||
description: Not Found
|
||
content:
|
||
application/json:
|
||
schema: { $ref: "#/components/schemas/ErrorResponse" }
|