Skip to content

Commit 094f9cc

Browse files
committed
feat(database): 🗄️ add MySQL database support design and requirements
- Add unified database query interface supporting SQL and NO-SQL - Design queryDatabase, executeDatabaseQuery, and manageDatabase tools - Support listTables, execute query, and getSDKDocs operations - Remove queryDocuments and collectionQuery tools (replaced by unified tools) - Remove insertDocuments, updateDocuments, deleteDocuments (replaced by manageDatabase) - Keep createCollection, updateCollection, checkIndexExists for management operations - Total tools: 37 (add 3, remove 5, within 40 limit)
1 parent 0bfd4f8 commit 094f9cc

File tree

4 files changed

+669
-0
lines changed

4 files changed

+669
-0
lines changed
Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# 设计评审 - 工具设计清晰度分析
2+
3+
## 当前设计的问题
4+
5+
### 1. 不一致性
6+
- **SQL 数据库**:查询和写操作都用 `executeDatabaseQuery`(统一)
7+
- **NO-SQL 数据库**:查询用 `executeDatabaseQuery`,但写操作用独立的 `insertDocuments``updateDocuments``deleteDocuments`(不一致)
8+
9+
### 2. 用户困惑点
10+
- 用户说"列出数据库表"时,不知道用哪个工具
11+
- SQL 和 NO-SQL 的操作方式不一致,学习成本高
12+
- 查询统一了,但写操作没有统一
13+
14+
### 3. 工具职责不清
15+
- `executeDatabaseQuery` 既用于查询,又用于写操作(SQL)
16+
- NO-SQL 的写操作有独立工具,但 SQL 的写操作没有
17+
18+
## 更清晰的设计方案
19+
20+
### 方案 A:完全统一(推荐)
21+
22+
**设计思路**:所有数据库操作(SQL 和 NO-SQL)都通过统一接口
23+
24+
**工具设计**
25+
1. `queryDatabase` - 只读操作
26+
- `action: 'listTables'` - 列出表/集合
27+
- `action: 'getSDKDocs'` - 获取 SDK 文档
28+
- 支持 SQL 和 NO-SQL
29+
30+
2. `executeDatabaseQuery` - 执行查询(只读查询)
31+
- SQL: `query: 'SELECT ...'`
32+
- NO-SQL: `query: {...}` (查询条件对象)
33+
- 标记为只读:`readOnlyHint: true`
34+
35+
3. `manageDatabase` - 数据操作(写操作)
36+
- `action: 'insert' | 'update' | 'delete'`
37+
- SQL: `query: 'INSERT/UPDATE/DELETE ...'`
38+
- NO-SQL:
39+
- insert: `documents: [...]`
40+
- update: `query: {...}, update: {...}`
41+
- delete: `query: {...}`
42+
43+
**优势**
44+
- 完全统一,SQL 和 NO-SQL 操作方式一致
45+
- 职责清晰:查询 vs 写操作
46+
- 用户学习成本低
47+
48+
**劣势**
49+
- `manageDatabase` 的参数结构可能较复杂(需要支持 SQL 和 NO-SQL 的不同参数)
50+
51+
### 方案 B:保持现状但优化
52+
53+
**设计思路**:查询统一,写操作保留独立工具,但明确说明原因
54+
55+
**工具设计**
56+
- 保持当前设计
57+
- 但明确文档说明:
58+
- SQL 写操作:通过 `executeDatabaseQuery` 执行 SQL 语句(因为 SQL 本身就是统一的语言)
59+
- NO-SQL 写操作:使用独立工具(因为参数结构特殊,不适合通用接口)
60+
61+
**优势**
62+
- 实现简单,改动小
63+
- SQL 写操作已经统一(通过 SQL 语句)
64+
65+
**劣势**
66+
- 仍然存在不一致性
67+
- 用户需要理解两种不同的操作方式
68+
69+
### 方案 C:SQL 和 NO-SQL 完全分开
70+
71+
**设计思路**:SQL 和 NO-SQL 使用不同的工具集
72+
73+
**工具设计**
74+
- SQL 工具:`querySQL`, `executeSQL`
75+
- NO-SQL 工具:保留现有的 `queryDocuments`, `insertDocuments`
76+
77+
**优势**
78+
- 职责非常清晰
79+
- 每种数据库类型有专门工具
80+
81+
**劣势**
82+
- 失去统一性
83+
- 工具数量增加
84+
- 用户说"列出数据库表"时,需要明确指定类型
85+
86+
## 推荐方案
87+
88+
**推荐采用方案 A(完全统一)**,原因:
89+
1. 用户体验最好:统一的操作方式
90+
2. 职责清晰:查询 vs 写操作
91+
3. 易于扩展:未来支持 PostgreSQL 等数据库时,只需扩展 `dbType`
92+
93+
**实现要点**
94+
- `manageDatabase` 工具需要支持 SQL 和 NO-SQL 的不同参数结构
95+
- 可以通过 `action` 参数区分操作类型
96+
- SQL 操作通过 `query` 参数传递 SQL 语句
97+
- NO-SQL 操作通过专门的参数(`documents`, `query`, `update` 等)
98+

0 commit comments

Comments
 (0)