ViperEkura
/
nanoClaw
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
nanoClaw/docs/Design.md

7.7 KiB
Raw Blame History

对话系统后端 API 设计

API 总览

会话管理

方法 路径 说明
POST /api/conversations 创建会话
GET /api/conversations 获取会话列表
GET /api/conversations/:id 获取会话详情
PATCH /api/conversations/:id 更新会话
DELETE /api/conversations/:id 删除会话

消息管理

方法 路径 说明
GET /api/conversations/:id/messages 获取消息列表
POST /api/conversations/:id/messages 发送消息（对话补全，支持 stream 流式）
DELETE /api/conversations/:id/messages/:message_id 删除消息

API 接口

1. 会话管理

创建会话

POST /api/conversations

请求体：

{
  "title": "新对话",
  "model": "glm-5",
  "system_prompt": "你是一个有帮助的助手",
  "temperature": 1.0,
  "max_tokens": 65536,
  "thinking_enabled": false
}

响应：

{
  "code": 0,
  "data": {
    "id": "conv_abc123",
    "title": "新对话",
    "model": "glm-5",
    "system_prompt": "你是一个有帮助的助手",
    "temperature": 1.0,
    "max_tokens": 65536,
    "thinking_enabled": false,
    "created_at": "2026-03-24T10:00:00Z",
    "updated_at": "2026-03-24T10:00:00Z"
  }
}

获取会话列表

GET /api/conversations?cursor=conv_abc123&limit=20
参数 类型 说明
cursor string 分页游标，为空取首页
limit integer 每页数量，默认 20，最大 100

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "conv_abc123",
        "title": "新对话",
        "model": "glm-5",
        "created_at": "2026-03-24T10:00:00Z",
        "updated_at": "2026-03-24T10:05:00Z",
        "message_count": 6
      }
    ],
    "next_cursor": "conv_def456",
    "has_more": true
  }
}

获取会话详情

GET /api/conversations/:id

响应：

{
  "code": 0,
  "data": {
    "id": "conv_abc123",
    "title": "新对话",
    "model": "glm-5",
    "system_prompt": "你是一个有帮助的助手",
    "temperature": 1.0,
    "max_tokens": 65536,
    "thinking_enabled": false,
    "created_at": "2026-03-24T10:00:00Z",
    "updated_at": "2026-03-24T10:05:00Z"
  }
}

更新会话

PATCH /api/conversations/:id

请求体（仅传需更新的字段）：

{
  "title": "修改后的标题",
  "system_prompt": "新的系统提示词",
  "temperature": 0.8
}

响应： 同获取会话详情

删除会话

DELETE /api/conversations/:id

响应：

{
  "code": 0,
  "message": "deleted"
}

2. 消息管理

获取消息列表

GET /api/conversations/:id/messages?cursor=msg_001&limit=50
参数 类型 说明
cursor string 分页游标
limit integer 每页数量，默认 50，最大 100

响应：

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "msg_001",
        "conversation_id": "conv_abc123",
        "role": "user",
        "content": "你好",
        "token_count": 2,
        "thinking_content": null,
        "created_at": "2026-03-24T10:00:00Z"
      },
      {
        "id": "msg_002",
        "conversation_id": "conv_abc123",
        "role": "assistant",
        "content": "你好！有什么可以帮你的？",
        "token_count": 15,
        "thinking_content": null,
        "created_at": "2026-03-24T10:00:01Z"
      }
    ],
    "next_cursor": "msg_003",
    "has_more": false
  }
}

发送消息（对话补全）

POST /api/conversations/:id/messages

请求体：

{
  "content": "介绍一下你的能力",
  "stream": true
}

流式响应 (stream=true)：

HTTP/1.1 200 OK
Content-Type: text/event-stream

event: thinking
data: {"content": "用户想了解我的能力..."}

event: message
data: {"content": "我是"}

event: message
data: {"content": "智谱AI"}

event: message
data: {"content": "开发的大语言模型"}

event: done
data: {"message_id": "msg_003", "token_count": 200}

非流式响应 (stream=false)：

{
  "code": 0,
  "data": {
    "message": {
      "id": "msg_003",
      "conversation_id": "conv_abc123",
      "role": "assistant",
      "content": "我是智谱AI开发的大语言模型...",
      "token_count": 200,
      "thinking_content": "用户想了解我的能力...",
      "created_at": "2026-03-24T10:01:00Z"
    },
    "usage": {
      "prompt_tokens": 50,
      "completion_tokens": 200,
      "total_tokens": 250
    }
  }
}

删除消息

DELETE /api/conversations/:id/messages/:message_id

响应：

{
  "code": 0,
  "message": "deleted"
}

3. SSE 事件说明

事件 说明
thinking 思维链增量内容（启用时）
message 回复内容的增量片段
error 错误信息
done 回复结束，携带完整 message_id 和 token 统计

4. 错误码

code 说明
0 成功
400 请求参数错误
401 未认证
403 无权限访问该资源
404 资源不存在
429 请求过于频繁
500 上游模型服务错误
503 服务暂时不可用

错误响应格式：

{
  "code": 404,
  "message": "conversation not found"
}

数据模型

ER 关系

User  1 ── * Conversation  1 ── * Message

Conversation（会话）

字段 类型 说明
id string (UUID) 会话 ID
user_id string 所属用户 ID
title string 会话标题
model string 使用的模型，默认 glm-5
system_prompt string 系统提示词
temperature float 采样温度，默认 1.0
max_tokens integer 最大输出 token，默认 65536
thinking_enabled boolean 是否启用思维链，默认 false
created_at datetime 创建时间
updated_at datetime 更新时间

Message（消息）

字段 类型 说明
id string (UUID) 消息 ID
conversation_id string 所属会话 ID
role enum user / assistant / system
content string 消息内容
token_count integer token 消耗数
thinking_content string 思维链内容（启用时）
created_at datetime 创建时间