跳转到主要内容

​
简介

管理用于关联任务与上下文的用户会话。 说明：
  • 仅支持软删除。DELETE 仅标记删除（保留数据），返回 204。
  • 被删除的会话会从读取结果中过滤，并且无法再被获取（返回 404）。

​
列出会话

GET /api/v1/sessions?limit=20&offset=0
查询参数：
  • limit（1–100，默认 20）
  • offset（>= 0，默认 0）
响应（200）： 
{
  "sessions": [
    {
      "session_id": "a0c2b1e2-...",
      "user_id": "00000000-0000-0000-0000-000000000002",
      "task_count": 3,
      "tokens_used": 1234,
      "token_budget": 10000,
      "created_at": "2025-10-28T06:00:00Z"
    }
  ],
  "total_count": 1
}

​
获取会话详情

GET /api/v1/sessions/{sessionId}
路径参数：
  • sessionId（uuid）
响应（200）：返回会话元数据（令牌用量、任务数量等）。 错误：401、403、404。

​
获取会话历史

GET /api/v1/sessions/{sessionId}/history
返回该会话下的所有任务及其执行细节。 错误：401、403、404。

​
获取会话事件（按轮次分组）

GET /api/v1/sessions/{sessionId}/events?limit=10&offset=0
按任务/轮次分组返回聊天历史，每个轮次包含完整事件列表（排除 LLM_PARTIAL）。 查询参数：
  • limit（1–100，默认 10）— 返回的轮次数
  • offset（>= 0，默认 0）— 跳过的轮次数
响应（200）： 
{
  "session_id": "chat-session-123",
  "count": 2,
  "turns": [
    {
      "turn": 1,
      "task_id": "task-001",
      "user_query": "What is 2+2?",
      "final_output": "2 + 2 equals 4.",
      "timestamp": "2025-10-29T06:00:01.513288Z",
      "events": [
        { "workflow_id": "wf-1", "type": "LLM_PROMPT", "message": "...", "timestamp": "..." },
        { "workflow_id": "wf-1", "type": "LLM_OUTPUT", "message": "2 + 2 equals 4.", "timestamp": "..." }
      ],
      "metadata": {
        "tokens_used": 150,
        "execution_time_ms": 8000,
        "agents_involved": ["planner", "simple-agent"]
      }
    }
  ]
}
说明：
  • 当任务结果为空时，final_output 回退为首条 LLM_OUTPUT 事件内容。
  • turn 为全局计数（offset + index）。
  • 会话被删除或不属于请求者时返回 404。

​
更新会话标题

PATCH /api/v1/sessions/{sessionId}
路径参数：
  • sessionId（UUID 或 external_id）
请求体： 
{ "title": "新标题" }
规则：
  • 标题会去除首尾空白并移除控制字符。
  • 最长 60 个字符（UTF-8 安全），更长将被拒绝。
响应：
  • 200 OK，返回更新后的标题
  • 400 无效请求（标题为空或过长）
  • 401 未授权
  • 403 禁止访问（非拥有者）
  • 404 未找到

​
删除会话（软删除）

DELETE /api/v1/sessions/{sessionId}
行为：
  • 标记会话为已删除（写入 deleted_at、deleted_by），不物理删除数据。
  • 幂等：对拥有者多次调用始终返回 204。
  • 清理会话缓存，避免读取到过期数据。
响应：
  • 204 No Content
  • 401 Unauthorized
  • 403 Forbidden（非拥有者）
  • 404 Not Found