> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shannon.run/llms.txt
> Use this file to discover all available pages before exploring further.

# 会话 API

> 列出、查看与删除会话（软删除）

## 简介

管理用于关联任务与上下文的用户会话。

说明：

* 仅支持软删除。`DELETE` 仅标记删除（保留数据），返回 204。
* 被删除的会话会从读取结果中过滤，并且无法再被获取（返回 404）。

## 列出会话

```
GET /api/v1/sessions?limit=20&offset=0
```

查询参数：

* `limit`（1–100，默认 20）
* `offset`（>= 0，默认 0）

响应（200）：

```json theme={null}
{
  "sessions": [
    {
      "session_id": "a0c2b1e2-...",
      "user_id": "00000000-0000-0000-0000-000000000002",
      "task_count": 3,
      "total_tokens_used": 1234,
      "token_budget": 10000,
      "created_at": "2025-10-28T06:00:00Z"
    }
  ],
  "total_count": 1
}
```

## 获取会话详情

```
GET /api/v1/sessions/{sessionId}
```

路径参数：

* `sessionId`（uuid）

响应（200）：返回会话元数据（Token用量、任务数量等）。
错误：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）：

```json theme={null}
{
  "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）

请求体：

```json theme={null}
{ "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