From a1150b957f0bd3e92ee07525a9b3803a2e652250 Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Tue, 4 Nov 2025 23:36:49 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E6=95=B0=E6=8D=AE?=
 =?UTF-8?q?=E5=BA=93=E6=8F=8F=E8=BF=B0=E6=94=AF=E6=8C=81=EF=BC=8C=E4=BC=98?=
 =?UTF-8?q?=E5=8C=96=E6=9F=A5=E8=AF=A2=E8=A1=A8=E5=90=8D=E5=B7=A5=E5=85=B7?=
 =?UTF-8?q?=E7=9A=84=E8=BE=93=E5=87=BA=E4=BF=A1=E6=81=AF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/advanced/agents-config.md            | 11 +++++++----
 src/agents/common/toolkits/mysql/tools.py |  7 +++++--
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/docs/advanced/agents-config.md b/docs/advanced/agents-config.md
index a75edbc1..6a51abb0 100644
--- a/docs/advanced/agents-config.md
+++ b/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` 后，智能体在列出数据库表时会优先展示这段说明，帮助模型在使用工具时理解库的用途，从而匹配更精确的查询策略。
 
 ### 安全特性
 
diff --git a/src/agents/common/toolkits/mysql/tools.py b/src/agents/common/toolkits/mysql/tools.py
index 3f12cac9..af21db4a 100644
--- a/src/agents/common/toolkits/mysql/tools.py
+++ b/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