跳到主要内容

版本 0.10 API 接口设计

生成时间：2026-01-09 18:53:39
使用模型：google/gemini-3-flash-preview

YOLOX 项目 API 设计方案 (v0.10)

本方案基于 React Native 前端、Golang (Eino) 后端、PostgreSQL 关系数据库及 Milvus 向量数据库构建，旨在实现用户冷启动、动态 Prompt 对话及 Memory 管理核心逻辑。

1. 认证与用户模块​

1.1 用户冷启动提交​

  • 路径: /api/v1/user/onboarding
  • 方法: POST
  • 描述: 提交新用户问卷结果，初始化用户画像并触发首次话题推荐。
  • 请求体:
{
  "answers": [
    {"question_id": "q1", "selected_options": ["opt_a"]},
    {"question_id": "q2", "selected_options": ["opt_b", "opt_c"]}
  ],
  "channel": "xiaohongshu"
}
  • 响应体:
{
  "status": "success",
  "recommended_topics": [
    {
      "topic_id": "t_001",
      "title": "分手后的深夜难熬时刻",
      "cover_url": "https://r2.yolox.ai/assets/t1.png",
      "level": "banner",
      "button_text": "开始倾诉"
    }
  ]
}

2. 话题与 Feed 模块​

2.1 获取话题 Feed​

  • 路径: /api/v1/topics/feed
  • 方法: GET
  • 描述: 基于用户 Memory 和配置获取个性化话题列表。
  • 请求参数: page, page_size
  • 响应体:
{
  "items": [
    {
      "topic_id": "t_002",
      "title": "职场倦怠：我在逃避什么？",
      "cover_url": "https://r2.yolox.ai/assets/t2.png",
      "level": "normal",
      "reason": "基于你最近提到的职业压力"
    }
  ],
  "next_cursor": "..."
}

3. 对话 (Jot) 模块​

3.1 创建/进入会话​

  • 路径: /api/v1/chat/session
  • 方法: POST
  • 描述: 根据话题 ID 初始化对话，获取欢迎语。
  • 请求体:
{
  "topic_id": "t_001",
  "entry_point": "homepage_long_press"
}
  • 响应体:
{
  "session_id": "sess_9988",
  "welcome_message": "看到你最近在经历这段艰难的时期，今晚感觉还好吗？",
  "system_status": "ready"
}

3.2 发送消息 (流式)​

  • 路径: /api/v1/chat/message/send
  • 方法: POST
  • 描述: 发送语音识别后的文本或纯文本，通过 SSE 返回 AI 响应。
  • 请求体:
{
  "session_id": "sess_9988",
  "content": "我觉得特别孤独，尤其是关灯后。",
  "input_type": "voice",
  "stream": true
}
  • 响应体 (SSE 流):
data: {"chunk": "我", "status": "thinking"}
data: {"chunk": "能", "status": "thinking"}
data: {"chunk": "理解", "status": "thinking"}
data: {"done": true, "message_id": "msg_001"}

3.3 语音转文字 (ASR)​

  • 路径: /api/v1/audio/transcribe
  • 方法: POST
  • 描述: 上传音频流进行实时识别（支持中英混合、去口水词）。
  • 请求体: multipart/form-data (audio file/blob)
  • 响应体:
{
  "text": "就是...嗯...我感觉压力很大。",
  "cleaned_text": "我感觉压力很大。",
  "duration_ms": 1500
}

4. Memory 与 Insight 模块​

4.1 获取用户画像 (Memory)​

  • 路径: /api/v1/user/memory
  • 方法: GET
  • 描述: 获取 Module 1 组装所需的 Persona 数据。
  • 响应体:
{
  "persona": {
    "basic_info": {"age": 25, "job": "Designer"},
    "communication_style": "感性, 叙事性强",
    "core_concerns": ["亲密关系边界", "职业认同"],
    "known_boundaries": ["已婚", "不接受激进建议"]
  }
}

4.2 生成对话总结 (Summary/Insight)​

  • 路径: /api/v1/chat/session/:id/summary
  • 方法: POST
  • 描述: 触发 Agent 生成当前对话的 Insight 组件。
  • 响应体:
{
  "summary_id": "sum_001",
  "content_md": "### 核心洞察\n- **情绪模式**: 习惯通过购物缓解焦虑\n- **建议**: 尝试 5 分钟呼吸法",
  "type": "artifact"
}

5. 历史管理模块​

5.1 获取历史会话列表​

  • 路径: /api/v1/chat/history
  • 方法: GET
  • 描述: 侧边栏展示，按时间排序。
  • 响应体:
{
  "sessions": [
    {
      "session_id": "sess_9988",
      "title": "关于深夜孤独感的对话",
      "is_starred": true,
      "updated_at": "2026-01-07T10:00:00Z"
    }
  ]
}

5.2 会话操作 (Star/Rename)​

  • 路径: /api/v1/chat/session/:id/meta
  • 方法: PATCH
  • 描述: 修改标题或收藏状态。
  • 请求体:
{
  "title": "新的标题",
  "is_starred": true
}
  • 响应体: 返回 status: updated

6. 基础设施依赖说明​

  • RAG 通信: 后端 Golang 通过 gRPC 调用 yolox-rag 服务，传递 topic_id 和 user_query 进行向量检索。
  • 对象存储: 语音文件上传至 Cloudflare R2，数据库仅存储 URL。
  • 实时性: 对话流式输出采用标准 SSE (Server-Sent Events) 协议。