Merge branch 'main' of https://github.com/xerrors/Yuxi-Know

Author: xerrors

docs/advanced/agents-config.md

@@ -63,7 +63,7 @@ agent_manager.init_all_agents()
   - 工具名称形如 `query_<db_id前缀>`；描述来自知识库名称与说明
   - 在工具选择阶段，用描述帮助模型做针对性检索
 - MySQL 工具包：只读查询
-  - `mysql_list_tables`、`mysql_describe_table`、`mysql_query`
+  - `mysql_list_tables`（对话侧名称：查询表名及说明）、`mysql_describe_table`、`mysql_query`
   - 环境变量见下，具备超时/行数限制与注入防护
 
 MCP（Model Context Protocol）可接入外部可视化或其他工具能力：
@@ -85,6 +85,7 @@ MYSQL_HOST=192.168.1.100
 MYSQL_USER=username
 MYSQL_PASSWORD=your_secure_password
 MYSQL_DATABASE=database_name
+MYSQL_DATABASE_DESCRIPTION=业务主库（可选，用于工具提示）
 MYSQL_PORT=3306
 MYSQL_CHARSET=utf8mb4
 ```
@@ -93,9 +94,11 @@ MYSQL_CHARSET=utf8mb4
 
 | 工具名称 | 功能描述 |
 |----------|----------|
-| `mysql_list_tables` | 获取数据库中的所有表名 |
-| `mysql_describe_table` | 获取指定表的详细结构信息 |
-| `mysql_query` | 执行只读的 SQL 查询语句 |
+| `mysql_list_tables`（查询表名及说明） | 获取数据库中的所有表名，并在有配置时附带数据库说明 |
+| `mysql_describe_table` （描述表） | 获取指定表的详细结构信息 |
+| `mysql_query` （执行 SQL 查询）| 执行只读的 SQL 查询语句 |
+
+配置 `MYSQL_DATABASE_DESCRIPTION` 后，智能体在列出数据库表时会优先展示这段说明，帮助模型在使用工具时理解库的用途，从而匹配更精确的查询策略。
 
 ### 安全特性
 

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

@@ -32,6 +32,7 @@ def get_connection_manager() -> MySQLConnectionManager:
             "database": os.getenv("MYSQL_DATABASE"),
             "port": int(os.getenv("MYSQL_PORT", "3306")),
             "charset": "utf8mb4",
+            "description": os.getenv("MYSQL_DATABASE_DESCRIPTION", "默认 MySQL 数据库"),
         }
         # 验证配置完整性
         required_keys = ["host", "user", "password", "database"]
@@ -49,7 +50,7 @@ class TableListModel(BaseModel):
     pass
 
 
-@tool(name_or_callable="查询表名", args_schema=TableListModel)
+@tool(name_or_callable="查询表名及说明", args_schema=TableListModel)
 def mysql_list_tables() -> str:
     """获取数据库中的所有表名
 
@@ -85,7 +86,9 @@ def mysql_list_tables() -> str:
             #     except Exception:
             #         table_info.append(f"- {table_name} (无法获取行数)")
 
-            result = "数据库中的表:\n" + "\n".join(table_names)
+            result = f"数据库中的表:\n{'\n'.join(table_names)}"
+            if db_note := conn_manager.config.get('description'):
+                result = f"数据库说明: {db_note}\n\n" + result
             logger.info(f"Retrieved {len(table_names)} tables from database")
             return result