# 对话查询与删除（工作区内，API v1）

对话数据是**工作区级**的：同一个 `conversation_id` 只属于一个 workspace。

鉴权：所有接口都需要 `Authorization: Bearer <TOKEN>`

---

## 1) 获取对话列表

### GET `/api/v1/workspaces/{workspace_id}/conversations?limit=<n>&offset=<n>`

返回该 workspace 下的对话列表（按更新时间/文件 mtime 倒序）。

Query 参数：

- `limit`：可选，默认 20，范围 1~100
- `offset`：可选，默认 0

成功响应（200）：

```json
{
  "success": true,
  "data": [
    {
      "id": "conv_20260124_023218_677",
      "title": "新对话",
      "created_at": "2026-01-24T02:32:18.677Z",
      "updated_at": "2026-01-24T02:33:10.123Z",
      "run_mode": "fast",
      "model_key": "kimi",
      "custom_prompt_name": "custom_a",
      "personalization_name": "biz_mobile",
      "workspace_id": "ws1",
      "messages_count": 6
    }
  ],
  "total": 42
}
```

常见错误：

- `400`：workspace_id 不合法
- `401`：缺少或无效 token
- `503`：系统未初始化

---

## 2) 获取单个对话（元数据或完整内容）

### GET `/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}?full=0|1`

Query 参数：

- `full`：可选，默认 `0`
  - `0`：只返回对话文件内容，但 `messages` 字段会被置为 `null`（避免数据量太大）
  - `1`：返回完整对话内容（包含 `messages`）

成功响应（200，full=0）：

```json
{
  "success": true,
  "workspace_id": "ws1",
  "data": {
    "id": "conv_20260124_023218_677",
    "title": "新对话",
    "created_at": "2026-01-24T02:32:18.677Z",
    "updated_at": "2026-01-24T02:33:10.123Z",
    "messages": null,
    "metadata": { },
    "token_statistics": { }
  }
}
```

常见错误：

- `404`：对话不存在（该 workspace 下找不到文件）
- `500`：对话 JSON 解析失败（损坏/写入中断等）

---

## 3) 删除对话

### DELETE `/api/v1/workspaces/{workspace_id}/conversations/{conversation_id}`

删除指定对话（仅影响当前 workspace 的对话文件）。

成功响应（200）：

```json
{
  "success": true,
  "workspace_id": "ws1",
  "message": "对话已删除: conv_20260124_023218_677"
}
```

注意事项：

- 删除是“硬删除”（删除对话文件），当前实现不提供回收站。
- 若该 workspace 正在运行任务，建议客户端禁用删除操作（避免对话文件与运行状态不一致）。