agent-Specialization/api_doc/conversations.md

对话查询与删除（工作区内，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）：

{
  "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）：

{
  "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）：

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

注意事项：

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