feat: 极大的提升 SQL 工具调用的稳定性，移除 LIMINT 并将默认超时时间修改为 60s，添加MySQL连接管理器和安全检查功能，优化查询执行和错误处理逻辑

  - 重构 MySQLConnectionManager，在使用前验证游标，向使用者提供辅助函数，并使用基于线程池的超时机制替代 SIGALRM，使查询可运行长达 600 秒，同时安全地失效不良连接（src/agents/common/toolkits/mysql/connection.py）
  - 扩大安全防护中的允许超时窗口，移除未使用的限制验证器，并更新查询模型默认值（src/agents/common/toolkits/mysql/security.py，src/agents/common/toolkits/mysql/tools.py）
  - 使 mysql_query 依赖 execute_query_with_timeout，移除隐式 LIMIT 注入，确保失败时连接保持健康，扩展结果格式化和故障排除提示；记录 list-table 调用，并在避免按表 COUNT 扫描的同时，丰富 mysql_describe_table 的列注释（src/agents/common/toolkits/mysql/tools.py）
  - 将高级代理指南重命名为 agents-config，更新 VitePress 导航，并在文档中增加 LangGraph/MCP/MySQL 配置指导（docs/.vitepress/config.mts，docs/advanced/agents-config.md）
  - 调整路线图错误列表，将 LangGraph 工具问题标记为已解决，并跟踪 LightRAG 查看器的缺失功能（docs/changelog/roadmap.md）
  - 添加 CLAUDE.md，引导贡献者参阅 AGENTS.md 获取更多信息

Author: xerrors

CLAUDE.md

@@ -0,0 +1 @@
+Read AGENTS.md

docs/.vitepress/config.mts

@@ -35,7 +35,7 @@ export default defineConfig({
         items: [
           { text: '配置系统详解', link: '/advanced/configuration' },
           { text: '文档解析', link: '/advanced/document-processing' },
-          { text: '智能体', link: '/advanced/agents' },
+          { text: '智能体', link: '/advanced/agents-config' },
           { text: '品牌自定义', link: '/advanced/branding' },
           { text: '其他配置', link: '/advanced/misc' }
         ]

docs/advanced/agents.md docs/advanced/agents-config.mddocs/advanced/agents.md renamed to docs/advanced/agents-config.md

@@ -101,7 +101,7 @@ MYSQL_CHARSET=utf8mb4
 
 - ✅ **只读操作**: 仅允许 SELECT、SHOW、DESCRIBE、EXPLAIN 操作
 - ✅ **SQL 注入防护**: 严格的表名参数验证
-- ✅ **超时控制**: 默认 10 秒，最大 60 秒
+- ✅ **超时控制**: 默认 60 秒，最大 600 秒
 - ✅ **结果限制**: 默认 10000 字符，100 行，最大 1000 行
 
 ### 可视化图表-MCP-Server

docs/changelog/roadmap.md

@@ -7,8 +7,8 @@
 
 ## Bugs
 
-- [ ] v1 版本的 LangGraph 的工具渲染有问题
 - [ ] upload 接口会阻塞主进程
+- [ ] LightRAG 知识库查看不了解析后的文本
 
 ## Next
 
@@ -39,4 +39,5 @@
 - [x] 修改现有的智能体Demo，并尽量将默认助手的特性兼容到 LangGraph 的 [`create_agent`](https://docs.langchain.com/oss/python/langchain/agents) 中
 - [x] 基于 create_agent 创建 SQL Viewer 智能体 <Badge type="info" text="0.3.5" />
 - [x] 优化 MCP 逻辑，支持 common + special 创建方式 <Badge type="info" text="0.3.5" />
-- [x] 修复本地知识库的 metadata 和 向量数据库中不一致的情况。
+- [x] 修复本地知识库的 metadata 和 向量数据库中不一致的情况。
+- [x] v1 版本的 LangGraph 的工具渲染有问题

src/agents/common/toolkits/mysql/connection.py

@@ -1,4 +1,4 @@
-import signal
+import concurrent.futures
 import threading
 import time
 from contextlib import contextmanager
@@ -93,55 +93,85 @@ def test_connection(self) -> bool:
             pass
         return False
 
+    def _invalidate_connection(self, connection: pymysql.Connection | None = None):
+        """关闭并清理失效的连接"""
+        try:
+            if connection:
+                connection.close()
+        except Exception:
+            pass
+        finally:
+            self.connection = None
+
     @contextmanager
     def get_cursor(self):
         """获取数据库游标的上下文管理器"""
         max_retries = 2
+        cursor = None
+        connection = None
+        last_error: Exception | None = None
+
+        # 优先确保成功获取游标再交给调用方执行查询
         for attempt in range(max_retries):
             try:
                 connection = self._get_connection()
                 cursor = connection.cursor()
-
-                try:
-                    yield cursor
-                    connection.commit()
-                    break  # 成功，退出重试循环
-
-                except Exception as e:
-                    connection.rollback()
-
-                    # 如果是连接错误，尝试重新连接
-                    if "MySQL" in str(e) or "connection" in str(e).lower():
-                        if attempt < max_retries - 1:
-                            logger.warning(f"Connection error, retrying (attempt {attempt + 1}): {e}")
-                            # 强制重新连接
-                            if self.connection:
-                                try:
-                                    self.connection.close()
-                                except Exception as _:
-                                    pass
-                            self.connection = None
-                            time.sleep(1)
-                            continue
-
-                    raise e  # 其他错误直接抛出
-
-                finally:
-                    if cursor:
-                        cursor.close()
-
+                break
             except Exception as e:
+                last_error = e
+                logger.warning(f"Failed to acquire cursor (attempt {attempt + 1}): {e}")
+                self._invalidate_connection(connection)
+                cursor = None
+                connection = None
                 if attempt == max_retries - 1:
-                    raise e  # 最后一次尝试失败，抛出异常
+                    raise e
                 time.sleep(1)
 
+        if cursor is None or connection is None:
+            raise last_error or ConnectionError("Unable to acquire MySQL cursor")
+
+        try:
+            yield cursor
+            connection.commit()
+        except Exception as e:
+            try:
+                connection.rollback()
+            except Exception:
+                pass
+
+            # 标记连接失效，等待下一次获取时重建
+            if "MySQL" in str(e) or "connection" in str(e).lower():
+                logger.warning(f"MySQL connection error encountered, invalidating connection: {e}")
+                self._invalidate_connection(connection)
+
+            raise
+        finally:
+            if cursor:
+                try:
+                    cursor.close()
+                except Exception:
+                    pass
+
     def close(self):
         """关闭数据库连接"""
         if self.connection:
             self.connection.close()
             self.connection = None
             logger.info("MySQL connection closed")
 
+    def get_connection(self) -> pymysql.Connection:
+        """对外暴露的连接获取方法"""
+        return self._get_connection()
+
+    def invalidate_connection(self):
+        """手动标记连接失效"""
+        self._invalidate_connection(self.connection)
+
+    @property
+    def database_name(self) -> str:
+        """返回当前配置的数据库名称"""
+        return self.config["database"]
+
 
 class QueryTimeoutError(Exception):
     """查询超时异常"""
@@ -156,25 +186,30 @@ class QueryResultTooLargeError(Exception):
 
 
 def execute_query_with_timeout(connection: pymysql.Connection, sql: str, params: tuple = None, timeout: int = 10):
-    """带超时的查询执行"""
+    """使用线程池实现超时控制，避免信号导致的生成器问题"""
 
-    def timeout_handler(_signum, _frame):
-        raise QueryTimeoutError(f"Query timeout after {timeout} seconds")
-
-    # 设置信号处理
-    old_handler = signal.signal(signal.SIGALRM, timeout_handler)
-    signal.alarm(timeout)
-
-    try:
+    def query_worker():
+        """查询工作函数，在单独线程中执行"""
         cursor = connection.cursor(DictCursor)
-        cursor.execute(sql, params or ())
-        result = cursor.fetchall()
-        cursor.close()
-        return result
-    finally:
-        # 恢复原始信号处理
-        signal.alarm(0)
-        signal.signal(signal.SIGALRM, old_handler)
+        try:
+            if params is None:
+                cursor.execute(sql)
+            else:
+                cursor.execute(sql, params)
+            result = cursor.fetchall()
+            return result
+        finally:
+            cursor.close()
+
+    # 使用线程池执行查询，设置超时
+    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
+        future = executor.submit(query_worker)
+        try:
+            return future.result(timeout=timeout)
+        except concurrent.futures.TimeoutError:
+            # 尝试取消任务
+            future.cancel()
+            raise QueryTimeoutError(f"Query timeout after {timeout} seconds")
 
 
 def limit_result_size(result: list, max_chars: int = 10000) -> list:

src/agents/common/toolkits/mysql/security.py

@@ -76,12 +76,7 @@ def validate_table_name(cls, table_name: str) -> bool:
         # 检查表名只包含字母、数字、下划线
         return bool(re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", table_name))
 
-    @classmethod
-    def validate_limit(cls, limit: int) -> bool:
-        """验证limit参数"""
-        return isinstance(limit, int) and 0 < limit <= 1000
-
     @classmethod
     def validate_timeout(cls, timeout: int) -> bool:
         """验证timeout参数"""
-        return isinstance(timeout, int) and 1 <= timeout <= 60
+        return isinstance(timeout, int) and 1 <= timeout <= 600