API文档
聊天会话
聊天会话和消息 API
创建会话
POST
/chats Auth 创建一个新的私聊会话，需要指定对话的角色 ID。
请求参数：
characterId
string required
关联的角色 ID（UUID 格式）
name
string
聊天会话名称
temporary
boolean
是否为临时会话
响应状态码：
| 状态码 | 说明 |
|---|---|
| 201 | 创建成功 |
| 400 | 输入参数无效 |
| 401 | 未登录或令牌无效 |
获取会话列表
GET
/chats Auth 获取当前用户的所有会话，支持分页。
查询参数：
page
string
页码，从 1 开始
limit
string
每页数量，1-100
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 获取成功 |
| 400 | 分页参数无效 |
| 401 | 未登录或令牌无效 |
获取会话详情
GET
/chats/{chatId} Auth 获取指定会话的详细信息，需要是会话的所有者。
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 获取成功 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话不存在 |
更新会话名称
PUT
/chats/{chatId}/name Auth 更新指定会话的名称，需要是会话的所有者。
请求参数：
name
string
新的会话名称
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 更新成功 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话不存在 |
删除会话
DELETE
/chats/{chatId} Auth 永久删除指定会话及其所有消息、配置和插件订阅，需要是会话的所有者。
响应状态码：
| 状态码 | 说明 |
|---|---|
| 204 | 删除成功 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话不存在 |
发送消息（SSE 流式响应）
POST
/chats/{chatId}/messages Auth 向指定会话发送消息并获取 AI 回复，响应为 SSE (Server-Sent Events) 流式格式。
请求参数：
content
MessageContentDto[] required
消息内容数组，支持多模态（文本、图片、文件、代码、音频、视频、PDF）
消息内容类型：
| 类型 | 字段 | 说明 |
|---|---|---|
text | content | 文本内容 |
image | url, alt | 图片地址和描述 |
file | url, fileName, fileSize | 文件信息 |
code | content, language | 代码内容和语言 |
audio | url, mimeType | 音频信息 |
video | url, mimeType | 视频信息 |
pdf | url, fileName | PDF 信息 |
SSE 事件类型：
| 事件 | 说明 |
|---|---|
delta | 增量文本 |
tool_call_start | 工具调用开始 |
tool_call_result | 工具调用结果 |
done | 完成 |
error | 错误 |
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | SSE 流式响应 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话不存在 |
获取历史消息
GET
/chats/{chatId}/messages Auth 获取指定会话的历史消息，支持分页，需要是会话的所有者。
查询参数：
page
string
页码，从 1 开始
limit
string
每页数量，1-100
说明：senderType 实际枚举值为 USER / CHARACTER。
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 获取成功 |
| 400 | 分页参数无效 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话不存在 |
删除指定消息
DELETE
/chats/{chatId}/messages/{messageId} Auth 删除指定会话中的指定消息。
响应状态码：
| 状态码 | 说明 |
|---|---|
| 204 | 删除消息成功 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话不存在 |
清空历史消息
DELETE
/chats/{chatId}/messages Auth 删除指定会话中的所有消息。
响应状态码：
| 状态码 | 说明 |
|---|---|
| 204 | 删除消息成功 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话不存在 |
获取会话配置
GET
/chats/{chatId}/config Auth 获取指定会话的 LLM 配置参数，需要是会话的所有者。
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 获取成功 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话不存在 |
更新会话配置
PUT
/chats/{chatId}/config Auth 更新指定会话的 LLM 配置参数，需要是会话的所有者。
请求参数：
temperature
number
温度参数 (0-2)，控制随机性
maxTokens
integer
最大生成 token 数
topP
number
Top-P 采样参数 (0-1)
systemPrompt
string
系统提示词
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 更新成功 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话不存在 |
获取插件订阅列表
GET
/chats/{chatId}/plugins Auth 获取指定会话的所有插件订阅，需要是会话的所有者。
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 获取成功 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话不存在 |
启用/禁用插件
PUT
/chats/{chatId}/plugins/{pluginId} Auth 为指定会话启用或禁用一个插件，如果订阅不存在则自动创建。
请求参数：
enabled
boolean required
是否启用
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 操作成功 |
| 400 | 插件状态不允许启用（如未审核通过） |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话或插件不存在 |
更新插件配置
PUT
/chats/{chatId}/plugins/{pluginId}/config Auth 更新指定会话中某个插件的配置参数，插件订阅必须已存在。
请求参数：
config
object required
插件配置（JSON 对象）
响应状态码：
| 状态码 | 说明 |
|---|---|
| 200 | 更新成功 |
| 401 | 未登录或令牌无效 |
| 403 | 权限不足 |
| 404 | 会话或插件订阅不存在 |