准备把当前版本提交到开发环境。

docs/QA反馈模块API调用说明.md

@@ -6,7 +6,7 @@
 QA反馈模块提供了完整的用户反馈管理功能，支持用户对问答结果进行点赞/点踩反馈，并将反馈数据转化为训练数据。本模块包含6个主要API端点，支持反馈记录的创建、查询、修改、删除以及训练数据集成。
 
 ### 🔧 基础信息
-- **基础URL**: `http://localhost:5000`
+- **基础URL**: `http://localhost:8084`
 - **API前缀**: `/api/v0/qa_feedback/`
 - **数据格式**: JSON
 - **字符编码**: UTF-8
@@ -18,8 +18,8 @@ QA反馈模块提供了完整的用户反馈管理功能，支持用户对问答
 | API端点 | 方法 | 功能描述 |
 |---------|------|----------|
 | `/api/v0/qa_feedback/query` | POST | 查询反馈记录（支持分页、筛选、排序） |
-| `/api/v0/qa_feedback/delete/{id}` | DELETE | 删除指定反馈记录 |
-| `/api/v0/qa_feedback/update/{id}` | PUT | 修改指定反馈记录 |
+| `/api/v0/qa_feedback/delete/{feedback_id}` | DELETE | 删除指定反馈记录 |
+| `/api/v0/qa_feedback/update/{feedback_id}` | PUT | 修改指定反馈记录 |
 | `/api/v0/qa_feedback/add_to_training` | POST | **核心功能**：批量添加到训练集 |
 | `/api/v0/qa_feedback/add` | POST | 创建新的反馈记录 |
 | `/api/v0/qa_feedback/stats` | GET | 获取反馈统计信息 |
@@ -85,31 +85,62 @@ QA反馈模块提供了完整的用户反馈管理功能，支持用户对问答
 
 ```json
 {
-  "code": 200,
-  "success": true,
-  "message": "查询成功，共找到 25 条记录",
-  "data": {
-    "records": [
-      {
-        "id": 1,
-        "question": "查询所有用户信息",
-        "sql": "SELECT * FROM users",
-        "is_thumb_up": true,
-        "user_id": "user123",
-        "create_time": "2024-06-24T10:30:00",
-        "is_in_training_data": false,
-        "update_time": null
-      }
-    ],
-    "pagination": {
-      "page": 1,
-      "page_size": 20,
-      "total": 25,
-      "total_pages": 2,
-      "has_next": true,
-      "has_prev": false
-    }
-  }
+    "code": 200,
+    "data": {
+        "pagination": {
+            "has_next": false,
+            "has_prev": false,
+            "page": 1,
+            "page_size": 5,
+            "total": 4,
+            "total_pages": 1
+        },
+        "records": [
+            {
+                "create_time": "2024-01-18T11:40:00",
+                "id": 8,
+                "is_in_training_data": false,
+                "is_thumb_up": true,
+                "question": "按月统计订单趋势",
+                "sql": "SELECT DATE_TRUNC('month', create_time) as month, COUNT(*) as order_count FROM orders GROUP BY month ORDER BY month;",
+                "update_time": null,
+                "user_id": "user007"
+            },
+            {
+                "create_time": "2024-01-17T13:25:00",
+                "id": 7,
+                "is_in_training_data": false,
+                "is_thumb_up": true,
+                "question": "查询用户余额",
+                "sql": "SELECT user_id, account_balance FROM user_accounts WHERE user_id = '12345';",
+                "update_time": null,
+                "user_id": "user006"
+            },
+            {
+                "create_time": "2024-01-16T16:30:00",
+                "id": 5,
+                "is_in_training_data": false,
+                "is_thumb_up": true,
+                "question": "查询今日新增用户",
+                "sql": "SELECT COUNT(*) as new_users FROM users WHERE DATE(create_time) = CURRENT_DATE;",
+                "update_time": null,
+                "user_id": "user005"
+            },
+            {
+                "create_time": "2024-01-16T09:45:00",
+                "id": 4,
+                "is_in_training_data": false,
+                "is_thumb_up": true,
+                "question": "按服务区统计营收",
+                "sql": "SELECT service_name, SUM(pay_sum) as total_revenue FROM bss_business_day_data WHERE delete_ts IS NULL GROUP BY service_name ORDER BY total_revenue DESC;",
+                "update_time": null,
+                "user_id": "user004"
+            }
+        ],
+        "response": "查询成功，共找到 4 条记录"
+    },
+    "message": "操作成功",
+    "success": true
 }
 ```
 
@@ -117,7 +148,7 @@ QA反馈模块提供了完整的用户反馈管理功能，支持用户对问答
 
 ### 2. 删除反馈记录 API
 
-**端点**: `DELETE /api/v0/qa_feedback/delete/{id}`
+**端点**: `DELETE /api/v0/qa_feedback/delete/{feedback_id}`
 
 **功能**: 根据记录ID删除指定的反馈记录。
 
@@ -125,7 +156,7 @@ QA反馈模块提供了完整的用户反馈管理功能，支持用户对问答
 
 | 参数名 | 类型 | 必填 | 说明 |
 |--------|------|------|------|
-| `id` | int | 是 | 反馈记录的ID |
+| `feedback_id` | int | 是 | 反馈记录的ID |
 
 #### 🌰 请求示例
 
@@ -165,7 +196,7 @@ DELETE /api/v0/qa_feedback/delete/123
 
 ### 3. 修改反馈记录 API
 
-**端点**: `PUT /api/v0/qa_feedback/update/{id}`
+**端点**: `PUT /api/v0/qa_feedback/update/{feedback_id}`
 
 **功能**: 修改指定反馈记录的内容。
 
@@ -173,7 +204,7 @@ DELETE /api/v0/qa_feedback/delete/123
 
 | 参数名 | 类型 | 必填 | 说明 |
 |--------|------|------|------|
-| `id` | int | 是 | 反馈记录的ID |
+| `feedback_id` | int | 是 | 反馈记录的ID |
 
 #### 📝 请求参数
 
@@ -349,14 +380,14 @@ GET /api/v0/qa_feedback/stats
 {
     "code": 200,
     "data": {
-        "negative_feedback": 10,
-        "positive_feedback": 8,
-        "positive_rate": 44.44,
         "response": "统计信息获取成功",
         "total_feedback": 18,
+        "positive_feedback": 8,
+        "negative_feedback": 10,
         "trained_feedback": 5,
-        "training_rate": 27.78,
-        "untrained_feedback": 13
+        "untrained_feedback": 13,
+        "positive_rate": 44.44,
+        "training_rate": 27.78
     },
     "message": "操作成功",
     "success": true
@@ -472,7 +503,7 @@ GET /api/v0/qa_feedback/stats
 ### 环境变量
 ```json
 {
-  "base_url": "http://localhost:5000",
+  "base_url": "http://localhost:8084",
   "api_prefix": "/api/v0/qa_feedback"
 }
 ```

docs/Redis对话管理API文档.md

@@ -28,7 +28,7 @@
 
 #### 请求示例
 ```http
-GET /api/v0/user/john_doe/conversations?limit=10
+GET /api/v0/user/guest/conversations?limit=10
 ```
 
 #### 响应示例
@@ -42,9 +42,11 @@ GET /api/v0/user/john_doe/conversations?limit=10
         "conversations": [
             {
                 "conversation_id": "conv_20241201_001",
-                "start_time": "2024-12-01T10:00:00",
-                "last_activity": "2024-12-01T10:30:00",
-                "message_count": 6
+                "user_id": "john_doe",
+                "created_at": "2024-12-01T10:00:00",
+                "updated_at": "2024-12-01T10:30:00",
+                "message_count": "6",
+                "conversation_title": "查询销售数据"
             }
         ],
         "total_count": 1
@@ -82,27 +84,33 @@ GET /api/v0/conversation/conv_20241201_001/messages?limit=50
     "data": {
         "conversation_id": "conv_20241201_001",
         "conversation_meta": {
+            "conversation_id": "conv_20241201_001",
+            "user_id": "john_doe",
             "created_at": "2024-12-01T10:00:00",
-            "message_count": 6
+            "updated_at": "2024-12-01T10:30:00",
+            "message_count": "6"
         },
         "messages": [
             {
+                "message_id": "msg_uuid_1",
                 "role": "user",
                 "content": "查询销售数据",
                 "timestamp": "2024-12-01T10:00:00",
                 "metadata": {}
             },
             {
+                "message_id": "msg_uuid_2",
                 "role": "assistant",
                 "content": "好的，我来帮您查询销售数据...",
                 "timestamp": "2024-12-01T10:00:05",
                 "metadata": {
                     "type": "DATABASE",
-                    "sql": "SELECT * FROM sales"
+                    "sql": "SELECT * FROM sales",
+                    "execution_path": ["start", "classify", "agent_database", "format_response"]
                 }
             }
         ],
-        "message_count": 6
+        "message_count": 2
     }
 }
 ```
@@ -182,29 +190,40 @@ GET /api/v0/user/john_doe/conversations/full?conversation_limit=20
         "conversations": [
             {
                 "conversation_id": "conv_20241201_001",
-                "start_time": "2024-12-01T10:00:00",
-                "last_activity": "2024-12-01T10:30:00",
+                "user_id": "john_doe",
+                "created_at": "2024-12-01T10:00:00",
+                "updated_at": "2024-12-01T10:30:00",
                 "meta": {
-                    "message_count": 6,
-                    "created_at": "2024-12-01T10:00:00"
+                    "conversation_id": "conv_20241201_001",
+                    "user_id": "john_doe",
+                    "created_at": "2024-12-01T10:00:00",
+                    "updated_at": "2024-12-01T10:30:00",
+                    "message_count": "6"
                 },
                 "messages": [
                     {
+                        "message_id": "msg_uuid_1",
                         "role": "user",
                         "content": "查询销售数据",
-                        "timestamp": "2024-12-01T10:00:00"
+                        "timestamp": "2024-12-01T10:00:00",
+                        "metadata": {}
                     },
                     {
+                        "message_id": "msg_uuid_2",
                         "role": "assistant",
                         "content": "好的，我来帮您查询销售数据...",
-                        "timestamp": "2024-12-01T10:00:05"
+                        "timestamp": "2024-12-01T10:00:05",
+                        "metadata": {
+                            "type": "DATABASE",
+                            "sql": "SELECT * FROM sales"
+                        }
                     }
                 ],
-                "message_count": 6
+                "message_count": 2
             }
         ],
         "total_conversations": 1,
-        "total_messages": 6,
+        "total_messages": 2,
         "conversation_limit_applied": null,
         "message_limit_applied": null,
         "query_time": "2024-12-01T15:30:00"
@@ -236,16 +255,13 @@ GET /api/v0/conversation_stats
     "code": 200,
     "message": "获取统计信息成功",
     "data": {
+        "available": true,
         "total_users": 125,
         "total_conversations": 1250,
-        "total_messages": 5000,
-        "active_users_today": 45,
-        "active_conversations_today": 200,
-        "cache_hit_rate": 0.75,
+        "cached_qa_count": 500,
         "redis_info": {
-            "connected": true,
-            "memory_usage": "120MB",
-            "keys_count": 2500
+            "memory_usage_mb": 120.5,
+            "connected_clients": 10
         }
     }
 }
@@ -274,11 +290,7 @@ POST /api/v0/conversation_cleanup
     "success": true,
     "code": 200,
     "message": "对话清理完成",
-    "data": {
-        "cleaned_conversations": 50,
-        "cleaned_messages": 200,
-        "cleanup_time": "2024-12-01T15:30:00"
-    }
+    "data": null
 }
 ```
 
@@ -300,6 +312,7 @@ POST /api/v0/conversation_cleanup
 | user_id | string | 请求体 | 否 | 用户ID |
 | conversation_id | string | 请求体 | 否 | 对话ID |
 | continue_conversation | boolean | 请求体 | 否 | 是否继续现有对话 |
+| routing_mode | string | 请求体 | 否 | 路由模式（database_direct, chat_direct, hybrid, llm_only） |
 
 #### 请求示例
 ```http
@@ -310,7 +323,8 @@ Content-Type: application/json
     "question": "查询最近一个月的销售数据",
     "session_id": "session_12345",
     "user_id": "john_doe",
-    "continue_conversation": true
+    "continue_conversation": true,
+    "routing_mode": "hybrid"
 }
 ```
 
@@ -319,12 +333,12 @@ Content-Type: application/json
 {
     "success": true,
     "code": 200,
-    "message": "查询执行完成",
+    "message": "操作成功",
     "data": {
         "type": "DATABASE",
-        "response": "",
+        "response": "查询到最近一个月的销售数据，共包含150条记录...",
         "sql": "SELECT * FROM sales WHERE date >= DATE_SUB(NOW(), INTERVAL 1 MONTH)",
-        "query_result": {
+        "records": {
             "rows": [...],
             "columns": ["date", "amount", "product"],
             "row_count": 150,
@@ -333,10 +347,10 @@ Content-Type: application/json
         },
         "summary": "查询到最近一个月的销售数据共150条记录...",
         "session_id": "session_12345",
-        "execution_path": ["classify_question", "generate_sql", "execute_sql", "generate_summary"],
+        "execution_path": ["start", "classify", "agent_database", "format_response"],
         "classification_info": {
-            "question_type": "DATABASE",
             "confidence": 0.95,
+            "reason": "用户询问销售数据统计",
             "method": "rule_based_database_keywords"
         },
         "conversation_id": "conv_20241201_002",
@@ -345,7 +359,12 @@ Content-Type: application/json
         "context_used": true,
         "from_cache": false,
         "conversation_status": "continued",
-        "conversation_message": "继续现有对话"
+        "conversation_message": "继续现有对话",
+        "requested_conversation_id": null,
+        "routing_mode_used": "hybrid",
+        "routing_mode_source": "api",
+        "agent_version": "langgraph_v1",
+        "timestamp": "2024-12-01T15:30:00"
     }
 }
 ```
@@ -387,7 +406,7 @@ Content-Type: application/json
     "code": 500,
     "message": "处理失败",
     "data": {
-        "error": "具体错误信息",
+        "response": "具体错误信息",
         "error_type": "error_type_code",
         "can_retry": true,
         "timestamp": "2024-12-01T15:30:00"
@@ -478,6 +497,8 @@ QUESTION_ANSWER_TTL = 24 * 3600      # 缓存过期时间（24小时）
 - 🆕 新增 `/api/v0/user/{user_id}/conversations/full` API
 - ✨ 支持一次性获取用户完整对话数据
 - 🔧 优化参数处理，支持不传递限制参数时返回所有记录
+- 🔄 **字段更新**: ask_agent API 响应中 query_result 改为 records
+- 📝 **新增字段**: conversation_title、routing_mode_used、routing_mode_source
 
 ### v1.0.0 (2024-11-01)
 - 🎉 首次发布 Redis 对话管理功能

docs/release/1.ask_agent API 说明.md

@@ -0,0 +1,395 @@
+## ask_agent()
+
+ask_agent()用来代替原来的ask() API，它采用LLM Agent技术，支持混合对话，即数据库查询和自由对话模式。
+
+### API端点一览
+
+|API端点|方法|功能描述|
+|-|-|-|
+|`/api/v0/ask_agent`|POST|智能问答查询（支持数据库查询和自由对话）|
+
+### 1.1.成功生成SQL并执行查询
+
+POST [http://localhost:8084/api/v0/ask_agent](http://localhost:8084/api/v0/ask_agent)
+
+```JSON
+{
+    "question": "请按照收入给每个高速服务区进行排名？返回收入最多的前三名服务区？"
+}
+
+#正常生成SQL,并完成查询的返回结果
+
+{
+    "code": 200,
+    "data": {
+        "agent_version": "langgraph_v1",
+        "classification_info": {
+            "confidence": 0.9,
+            "method": "rule_based_strong_business",
+            "reason": "强业务特征 - 业务实体: ['核心业务实体:服务区', '支付业务:收入'], 查询意图: ['排名'], SQL: []"
+        },
+        "context_used": false,
+        "conversation_id": "conv_1751199617_5d37a647",
+        "conversation_message": "创建新对话",
+        "conversation_status": "new",
+        "execution_path": [
+            "start",
+            "classify",
+            "agent_sql_generation",
+            "agent_sql_execution",
+            "format_response"
+        ],
+        "from_cache": false,
+        "is_guest_user": true,
+        "records": {
+            "columns": [
+                "服务区名称",
+                "总收入"
+            ],
+            "is_limited": false,
+            "row_count": 3,
+            "rows": [
+                {
+                    "总收入": "7024226.1500",
+                    "服务区名称": "庐山服务区"
+                },
+                {
+                    "总收入": "6929288.3300",
+                    "服务区名称": "三清山服务区"
+                },
+                {
+                    "总收入": "6848435.6700",
+                    "服务区名称": "南城服务区"
+                }
+            ],
+            "total_row_count": 3
+        },
+        "response": "根据收入排名，前三名高速服务区依次为：庐山服务区（702.42万元）、三清山服务区（692.93万元）、南城服务区（684.84万元）。",
+        "routing_mode_source": "config",
+        "routing_mode_used": "hybrid",
+        "session_id": null,
+        "sql": "SELECT service_name AS 服务区名称, SUM(pay_sum) AS 总收入 \nFROM bss_business_day_data \nWHERE delete_ts IS NULL \nGROUP BY service_name \nORDER BY 总收入 DESC NULLS LAST \nLIMIT 3;",
+        "summary": "根据收入排名，前三名高速服务区依次为：庐山服务区（702.42万元）、三清山服务区（692.93万元）、南城服务区（684.84万元）。",
+        "timestamp": "2025-06-29T20:20:56.806141",
+        "type": "DATABASE",
+        "user_id": "guest"
+    },
+    "message": "操作成功",
+    "success": true
+}
+
+```
+
+前端UI应关注的参数：
+
+1."response": 它将代替原来的summary，会查询的结果进行总结。
+
+2."sql"：执行查询SQL.
+
+3."data.records"：查询返回的数据，包括表头(data.records.columns)和数据行(data.records.rows)
+
+### 1.2.未成功生成SQL
+
+POST [http://localhost:8084/api/v0/ask_agent](http://localhost:8084/api/v0/ask_agent)
+
+```JSON
+{
+    "question": "请问每个高速公路服务区的管理经理是谁？"
+
+}
+
+# 返回结果
+{
+    "code": 200,
+    "data": {
+        "agent_version": "langgraph_v1",
+        "classification_info": {
+            "confidence": 0.82,
+            "method": "rule_based_medium_business",
+            "reason": "中等业务特征 - 业务实体: ['核心业务实体:服务区', '核心业务实体:高速公路']"
+        },
+        "context_used": false,
+        "conversation_id": "conv_1751201276_e59f0a07",
+        "conversation_message": "创建新对话",
+        "conversation_status": "new",
+        "execution_path": [
+            "start",
+            "classify",
+            "agent_sql_generation",
+            "format_response"
+        ],
+        "from_cache": false,
+        "is_guest_user": true,
+        "response": "当前提供的上下文信息不足以生成查询服务区对应管理经理的SQL语句。原因如下：\n\n1. 在服务区管理公司表(bss_company)中虽然存在created_by/updated_by字段，但这些字段仅记录数据操作者（系统用户），而非实际的管理经理人员信息。\n\n2. 现有表结构中缺失以下关键实体：\n   - 员工/人员信息表（存储经理姓名等个人信息）\n   - 公司与人员的组织架构表（关联公司ID与员工ID）\n\n3. 当前表间关系仅能查询到服务区所属的管理公司名称（通过bss_service_area.company_id关联bss_company.id），但无法获取具体管理人员的姓名。\n\n需要补充以下信息才能继续：\n- 存储人员信息的表结构（特别是管理岗位人员）\n- 公司与人员的关联关系表结构 请尝试提问其它问题。",
+        "routing_mode_source": "config",
+        "routing_mode_used": "hybrid",
+        "session_id": null,
+        "timestamp": "2025-06-29T20:48:21.351324",
+        "type": "DATABASE",
+        "user_id": "guest"
+    },
+    "message": "操作成功",
+    "success": true
+}
+
+
+```
+
+前端UI应关注的参数：
+
+1.没有返回"sql"和"data.records"。
+
+2."response":当没有返回"sql"和"data.records"的时候，response会返回未能生成SQL的原因，可以返回给客户端。
+
+
+
+### 1.3.在Post中传递路由参数
+
+当Post 参数中，没有包含routing_mode 参数时，默认会采用服务配置文件app_config.py中"QUESTION_ROUTING_MODE "参数，它的默认值是"hybrid"。
+
+这个routing_mode 参数的含义是，手工调整查询数据库或自由对话的路由。例如，当我们在切换话题时，如果LLM不能及时的从数据库查询/自由对话模式路由到正确模式，那么需要通过传递这个参数来强迫系统查询数据库，或自由对话。它为对话提供一个兜底方案。
+
+我们可以在对话框的下方或者右侧合适的位置，添加两个按钮"数据查询模式"和"自由对话模式"，当点击"数据查询模式时"，在POST参数中自动添加"routing_mode: database_direct"，当点击"自由对话模式"，在POST参数中自动添加"routing_mode: chat_direct".
+
+```Markdown
+routing_mode (string, 可选)
+问题路由模式，控制AI如何处理问题
+有效值：
+- "database_direct": 直接数据库查询模式
+- "chat_direct": 直接聊天模式
+
+```
+
+举例说明：
+
+POST [http://localhost:8084/api/v0/ask_agent](http://localhost:8084/api/v0/ask_agent)
+
+下面的例子，如果不添加 "routing_mode": "database_direct"，这个问题会被路由到自由查询模式，因为数据库中没有充电桩的数据。但 "routing_mode": "database_direct" 参数会强迫系统查询数据库。
+
+```JSON
+{
+    "question": "请问中国共有多少个充电桩",
+    "routing_mode": "database_direct"
+
+}
+
+# 上面的参数，返回结果：
+
+{
+    "code": 200,
+    "data": {
+        "agent_version": "langgraph_v1",
+        "classification_info": {
+            "confidence": 1,
+            "method": "direct_database",
+            "reason": "配置为直接数据库查询模式"
+        },
+        "context_used": false,
+        "conversation_id": "conv_1751202425_d04139e4",
+        "conversation_message": "创建新对话",
+        "conversation_status": "new",
+        "execution_path": [
+            "start",
+            "init_direct_database",
+            "agent_sql_generation",
+            "format_response"
+        ],
+        "from_cache": false,
+        "is_guest_user": true,
+        "response": "提供的上下文未包含充电桩相关数据字段，无法统计中国充电粧总数。当前数据库中服务区相关表（bss_service_area）未记录充电粧数量信息，建议确认业务表结构或补充数据来源。 请尝试提问其它问题。",
+        "routing_mode_source": "api",
+        "routing_mode_used": "database_direct",
+        "session_id": null,
+        "timestamp": "2025-06-29T21:07:26.383228",
+        "type": "DATABASE",
+        "user_id": "guest"
+    },
+    "message": "操作成功",
+    "success": true
+}
+
+
+```
+
+
+
+### 1.4. 关于用户认证
+
+按照项目组的约定，将来会从Post中获取token令牌，然后通过API获取user_id。在当前系统中，暂时没有提供用户验证功能。出于测试目的可以传递user_id，不同的user_id会看到属于自己的对话记录。
+
+如果没有传递user_id，那么将使用默认用户guest.
+
+POST [http://localhost:8084/api/v0/ask_agent](http://localhost:8084/api/v0/ask_agent)
+
+```JSON
+{
+    "question": "请问中国共有多少个充",
+    "user_id": "Paul"
+}
+```
+
+
+
+### 1.5.关于上下文对话的传递(多轮对话)
+
+每个用户user_id，默认会保存最近5次的"会话"(conversation_id)，每个conversation_id会保存10组对话信息。每次上下文传递默认会传递最近2次的对话上下文。
+
+这些参数在app_config.py中进行控制：
+
+```Python
+# app_config.py 的对话上下文配置
+CONVERSATION_CONTEXT_COUNT = 2          # 传递给LLM的上下文消息条数
+CONVERSATION_MAX_LENGTH = 10            # 单个对话最大消息数
+USER_MAX_CONVERSATIONS = 5              # 用户最大对话数
+
+```
+
+**第一轮对话**：
+
+POST [http://localhost:8084/api/v0/ask_agent](http://localhost:8084/api/v0/ask_agent)
+
+```JSON
+{
+    "question": "请问哪个服务区的档口最多？",
+    "user_id": "Paul"
+}
+
+# 请注意在下面的返回的结果中，包含了 "data.conversation_id",
+# "conversation_id": "conv_1751205549_308eb7c3",
+
+{
+    "code": 200,
+    "data": {
+        "agent_version": "langgraph_v1",
+        "classification_info": {
+            "confidence": 0.82,
+            "method": "rule_based_medium_business",
+            "reason": "中等业务特征 - 业务实体: ['核心业务实体:服务区', '核心业务实体:档口']"
+        },
+        "context_used": false,
+        "conversation_id": "conv_1751205549_308eb7c3",
+        "conversation_message": "创建新对话",
+        "conversation_status": "new",
+        "execution_path": [
+            "start",
+            "classify",
+            "agent_sql_generation",
+            "agent_sql_execution",
+            "format_response"
+        ],
+        "from_cache": false,
+        "is_guest_user": false,
+        "records": {
+            "columns": [
+                "服务区名称",
+                "档口数量"
+            ],
+            "is_limited": false,
+            "row_count": 1,
+            "rows": [
+                {
+                    "服务区名称": "南城服务区",
+                    "档口数量": 39
+                }
+            ],
+            "total_row_count": 1
+        },
+        "response": "南城服务区的档口数量最多，共计39个。",
+        "routing_mode_source": "config",
+        "routing_mode_used": "hybrid",
+        "session_id": null,
+        "sql": "SELECT sa.service_area_name AS 服务区名称, COUNT(b.id) AS 档口数量 FROM bss_service_area sa JOIN bss_branch b ON sa.id = b.service_area_id WHERE sa.delete_ts IS NULL AND b.delete_ts IS NULL GROUP BY sa.service_area_name ORDER BY 档口数量 DESC NULLS LAST LIMIT 1;",
+        "summary": "南城服务区的档口数量最多，共计39个。",
+        "timestamp": "2025-06-29T22:00:17.154155",
+        "type": "DATABASE",
+        "user_id": "Paul"
+    },
+    "message": "操作成功",
+    "success": true
+}
+
+```
+
+
+
+请前端UI关注"conversation_id": "conv_1751205549_308eb7c3"，当第二次或后续再次提交POST的时候，传递相同的"user_id"和"conversation_id"，后台服务就会把相同的"conversation_id"作为一次会话保存。再提交问题给LLM的时候，会把前面两次对话记录传递给LLM。
+
+**第二轮对话**，注意POST参数中提供了第一轮对话中返回的"conversation_id"，然后在第二个问题中延续了第一个问题中的答案。
+
+POST [http://localhost:8084/api/v0/ask_agent](http://localhost:8084/api/v0/ask_agent)
+
+```JSON
+{
+    "conversation_id": "conv_1751205549_308eb7c3",
+    "question": "请问这个服务区的餐饮档口有几个？",
+    "user_id": "Paul"
+}
+
+# 返回结果
+{
+    "code": 200,
+    "data": {
+        "agent_version": "langgraph_v1",
+        "classification_info": {
+            "confidence": 0.8799999999999999,
+            "method": "rule_based_medium_business",
+            "reason": "中等业务特征 - 业务实体: ['核心业务实体:服务区', '核心业务实体:档口', '经营品类:餐饮']"
+        },
+        "context_used": true,
+        "conversation_id": "conv_1751205549_308eb7c3",
+        "conversation_message": "继续已有对话",
+        "conversation_status": "existing",
+        "execution_path": [
+            "start",
+            "classify",
+            "agent_sql_generation",
+            "agent_sql_execution",
+            "format_response"
+        ],
+        "from_cache": false,
+        "is_guest_user": false,
+        "records": {
+            "columns": [
+                "餐饮档口数量"
+            ],
+            "is_limited": false,
+            "row_count": 1,
+            "rows": [
+                {
+                    "餐饮档口数量": 6
+                }
+            ],
+            "total_row_count": 1
+        },
+        "response": "该服务区餐饮档口数量为6个。",
+        "routing_mode_source": "config",
+        "routing_mode_used": "hybrid",
+        "session_id": null,
+        "sql": "SELECT COUNT(*) AS 餐饮档口数量 FROM bss_branch b JOIN bss_service_area sa ON b.service_area_id = sa.id WHERE sa.service_area_name = '南城服务区' AND b.classify = '餐饮' AND b.delete_ts IS NULL;",
+        "summary": "该服务区餐饮档口数量为6个。",
+        "timestamp": "2025-06-29T22:09:25.494134",
+        "type": "DATABASE",
+        "user_id": "Paul"
+    },
+    "message": "操作成功",
+    "success": true
+}
+
+```
+
+在debug的时候，可以注意上面的返回参数中"conversation_message"和  "conversation_status"在第一轮对话和第二轮对话中的值是不同的：
+
+第一轮对话：
+
+        `"conversation_message": "创建新对话",`
+        `"conversation_status": "new",`
+
+第二轮对话：
+
+        `"conversation_message": "继续已有对话",`
+       ` "conversation_status": "existing",`
+
+
+
+
+

docs/训练数据管理API调用说明.md

@@ -30,26 +30,26 @@ GET /api/v0/training_data/stats
 ### 响应示例
 ```json
 {
-  "code": 200,
-  "success": true,
-  "message": "操作成功",
-  "data": {
-    "total_count": 228,
-    "type_breakdown": {
-      "sql": 210,
-      "ddl": 9,
-      "documentation": 8,
-      "error_sql": 1
-    },
-    "type_percentages": {
-      "sql": 92.11,
-      "ddl": 3.95,
-      "documentation": 3.51,
-      "error_sql": 0.44
+    "code": 200,
+    "data": {
+        "last_updated": "2025-06-30T16:03:42.112380",
+        "response": "统计信息获取成功",
+        "total_count": 228,
+        "type_breakdown": {
+            "ddl": 9,
+            "documentation": 9,
+            "error_sql": 1,
+            "sql": 209
+        },
+        "type_percentages": {
+            "ddl": 3.95,
+            "documentation": 3.95,
+            "error_sql": 0.44,
+            "sql": 91.67
+        }
     },
-    "response": "统计信息获取成功",
-    "last_updated": "2025-06-24T17:39:36.895114"
-  }
+    "message": "操作成功",
+    "success": true
 }
 ```
 
@@ -83,32 +83,38 @@ POST /api/v0/training_data/query
 ### 响应示例
 ```json
 {
-  "code": 200,
-  "success": true,
-  "message": "操作成功",
-  "data": {
-    "records": [
-      {
-        "id": "fb113c5e-6cde-4653-ac5f-7558f6e634db-sql",
-        "training_data_type": "sql",
-        "question": "查看活跃用户列表",
-        "content": "SELECT user_id, user_name, last_login FROM users WHERE last_login >= CURRENT_DATE - INTERVAL '30 days';"
-      }
-    ],
-    "pagination": {
-      "page": 1,
-      "page_size": 5,
-      "total": 2,
-      "total_pages": 1,
-      "has_next": false,
-      "has_prev": false
-    },
-    "filters_applied": {
-      "training_data_type": "sql",
-      "search_keyword": "用户"
+    "code": 200,
+    "data": {
+        "filters_applied": {
+            "search_keyword": "用户",
+            "training_data_type": "sql"
+        },
+        "pagination": {
+            "has_next": false,
+            "has_prev": false,
+            "page": 1,
+            "page_size": 20,
+            "total": 2,
+            "total_pages": 1
+        },
+        "records": [
+            {
+                "content": "SELECT user_id, user_name, last_login FROM users WHERE last_login >= CURRENT_DATE - INTERVAL '30 days';",
+                "id": "fb113c5e-6cde-4653-ac5f-7558f6e634db-sql",
+                "question": "查看活跃用户列表",
+                "training_data_type": "sql"
+            },
+            {
+                "content": "SELECT * FROM users WHERE delete_ts IS NULL;",
+                "id": "06885f86-9d52-46f3-ad77-62ac455f6ea9-sql",
+                "question": "查询所有用户信息",
+                "training_data_type": "sql"
+            }
+        ],
+        "response": "查询成功，共找到 2 条记录"
     },
-    "response": "查询成功，共找到 2 条记录"
-  }
+    "message": "操作成功",
+    "success": true
 }
 ```
 
@@ -187,34 +193,75 @@ POST /api/v0/training_data/create
 ### 响应示例
 ```json
 {
-  "code": 200,
-  "success": true,
-  "message": "操作成功",
-  "data": {
-    "total_requested": 1,
-    "successfully_created": 1,
-    "failed_count": 0,
-    "results": [
-      {
-        "index": 0,
-        "success": true,
-        "type": "sql",
-        "training_id": "e1afe1c2-6956-4133-9cb6-0f83c5e1b12d-sql",
-        "message": "sql训练数据创建成功"
-      }
-    ],
-    "summary": {
-      "sql": 1,
-      "ddl": 0,
-      "documentation": 0,
-      "error_sql": 0
+    "code": 200,
+    "data": {
+        "current_total_count": 229,
+        "failed_count": 0,
+        "response": "训练数据创建完成",
+        "results": [
+            {
+                "index": 0,
+                "message": "sql训练数据创建成功",
+                "success": true,
+                "training_id": "f4903d4c-7c37-4140-bfde-930f0f50fbf3-sql",
+                "type": "sql"
+            }
+        ],
+        "successfully_created": 1,
+        "summary": {
+            "ddl": 0,
+            "documentation": 0,
+            "error_sql": 0,
+            "sql": 1
+        },
+        "total_requested": 1
     },
-    "current_total_count": 229,
-    "response": "训练数据创建完成"
-  }
+    "message": "操作成功",
+    "success": true
+}
+```
+
+
+
+```json
+{
+    "code": 200,
+    "data": {
+        "current_total_count": 231,
+        "failed_count": 0,
+        "response": "训练数据创建完成",
+        "results": [
+            {
+                "index": 0,
+                "message": "sql训练数据创建成功",
+                "success": true,
+                "training_id": "0d3dd858-b3a3-4eca-863a-a41c552862a2-sql",
+                "type": "sql"
+            },
+            {
+                "index": 1,
+                "message": "documentation训练数据创建成功",
+                "success": true,
+                "training_id": "59b802fd-e0f7-48b4-b207-afd170d41c37-doc",
+                "type": "documentation"
+            }
+        ],
+        "successfully_created": 2,
+        "summary": {
+            "ddl": 0,
+            "documentation": 1,
+            "error_sql": 0,
+            "sql": 1
+        },
+        "total_requested": 2
+    },
+    "message": "操作成功",
+    "success": true
 }
 ```
 
+
+
 ### SQL安全检查
 
 系统会自动检查SQL语句，禁止以下危险操作：
@@ -247,7 +294,7 @@ POST /api/v0/training_data/create
 ```
 
 ### 批量操作限制
-- 单次批量操作最多支持50条记录
+- 单次批量操作最多支持50条记录。
 - 超出限制会返回400错误
 
 ---
@@ -277,28 +324,22 @@ POST /api/v0/training_data/delete
 ### 响应示例
 ```json
 {
-  "code": 200,
-  "success": true,
-  "message": "操作成功",
-  "data": {
-    "total_requested": 2,
-    "successfully_deleted": 1,
-    "failed_count": 1,
-    "deleted_ids": [
-      "e1afe1c2-6956-4133-9cb6-0f83c5e1b12d-sql"
-    ],
-    "failed_ids": [
-      "0db3b76a-6fa5-4c8e-9115-3ec7cc6159fe-doc"
-    ],
-    "failed_details": [
-      {
-        "id": "0db3b76a-6fa5-4c8e-9115-3ec7cc6159fe-doc",
-        "error": "记录不存在或删除失败"
-      }
-    ],
-    "current_total_count": 228,
-    "response": "训练数据删除完成"
-  }
+    "code": 200,
+    "data": {
+        "current_total_count": 229,
+        "deleted_ids": [
+            "0d3dd858-b3a3-4eca-863a-a41c552862a2-sql",
+            "59b802fd-e0f7-48b4-b207-afd170d41c37-doc"
+        ],
+        "failed_count": 0,
+        "failed_details": [],
+        "failed_ids": [],
+        "response": "训练数据删除完成",
+        "successfully_deleted": 2,
+        "total_requested": 2
+    },
+    "message": "操作成功",
+    "success": true
 }
 ```