Skip to content

Commit 7b0369a

Browse files
committed
docs: update documentation links and download URLs
- Update KWDB documentation website links in README.md and README_zh.md - Add download links for KWDB MCP Server installation package in both Chinese and English integration guides - Remove ^M characters from documentation files
1 parent ea7fa70 commit 7b0369a

File tree

7 files changed

+1154
-1151
lines changed

7 files changed

+1154
-1151
lines changed

README.md

Lines changed: 340 additions & 340 deletions
Large diffs are not rendered by default.

README_zh.md

Lines changed: 330 additions & 330 deletions
Large diffs are not rendered by default.

docs/design.md

Lines changed: 160 additions & 160 deletions
Original file line numberDiff line numberDiff line change
@@ -1,160 +1,160 @@
1-
**开务数据库 MCP 服务设计文档 V1.0**
2-
3-
4-
5-
6-
1\. **文档说明**
7-
8-
1.1 **术语与缩写解释**
9-
10-
| 术语 | 说明 |
11-
|-------------|----------------------------------------------------------------------|
12-
| KWDB | 开务数据库(KaiwuDB)的开源版名称 |
13-
| SSE | Server-Sent Events,服务器推送事件协议 |
14-
| MCP | Model Context Protocol,模型上下文协议,用于LLM Agent与外部资源通信 |
15-
| Prompt | 提示词,用于指导AI模型生成特定类型的回应 |
16-
| LLM | Large Language Model,大型语言模型 |
17-
| Agent | 智能代理,能够根据用户输入执行任务的自动化系统 |
18-
| Tool | MCP协议提供的工具,Agent可调用的函数或服务 |
19-
| Resource | MCP协议提供的资源,Agent可查询或订阅的数据 |
20-
21-
22-
2\. **设计概述**
23-
24-
2.1 **架构设计**
25-
26-
```mermaid
27-
flowchart TD
28-
A[MCP协议层] --> B[工具调度器]
29-
A --> C[资源管理器]
30-
B --> D{查询类型判断}
31-
D -->|读操作| E[查询执行引擎]
32-
D -->|写操作| F[事务处理引擎]
33-
E --> G[结果格式化]
34-
F --> G
35-
G --> H[响应生成]
36-
C --> I[数据库元数据]
37-
C --> J[表结构信息]
38-
H --> A
39-
I --> E
40-
J --> E
41-
```
42-
43-
2.2 **核心流程**
44-
- 协议解析:处理MCP标准输入或HTTP SSE请求
45-
- 工具路由:根据工具类型(read/write)分发处理
46-
- 查询预处理:自动添加LIMIT、语法检查
47-
- 连接池管理:维护数据库连接的生命周期
48-
- 结果封装:统一JSON响应格式
49-
50-
3\. **功能设计**
51-
52-
3.1 **外部接口**
53-
54-
3.1.1 **MCP Tools 接口**
55-
```mermaid
56-
flowchart LR
57-
Tool[LLM Agent] -- JSON-RPC --> MCP_Server
58-
subgraph MCP_Server
59-
direction TB
60-
Tool_Dispatcher --> Read_Query
61-
Tool_Dispatcher --> Write_Query
62-
Read_Query --> DB_Conn[连接池]
63-
Write_Query --> DB_Conn
64-
end
65-
```
66-
67-
3.1.2 **接口定义**
68-
1. 读查询工具:
69-
```json
70-
{
71-
"name": "read-query",
72-
"input": {
73-
"sql": "SELECT * FROM table LIMIT 10"
74-
}
75-
}
76-
```
77-
78-
2. 写查询工具:
79-
```json
80-
{
81-
"name": "write-query",
82-
"input": {
83-
"sql": "INSERT INTO table VALUES(...)"
84-
}
85-
}
86-
```
87-
88-
3.2 **MCP Resources**
89-
| 资源类型 | URI格式 | 示例 |
90-
|-------------------------|----------------------------------|-------------------------------|
91-
| 数据库产品信息 | kwdb://product_info | kwdb://product_info/ |
92-
| 数据库元信息 | kwdb://db_info/{database_name} | kwdb://db_info/db_shig |
93-
| 表结构信息 | kwdb://table/{table_name} | kwdb://table/user_profile |
94-
95-
3.3 **Prompt管理架构**
96-
```mermaid
97-
flowchart TD
98-
A[Prompt Markdown文件] --> B[编译时嵌入]
99-
B --> C[运行时缓存]
100-
C --> D[LLM交互接口]
101-
D --> E[动态内容更新]
102-
B -->|版本控制| F[Git仓库]
103-
104-
subgraph 核心组件
105-
C --> G[Prompt缓存管理器]
106-
G --> H[查询处理器]
107-
end
108-
```
109-
110-
3.4 **Prompt分类规范**
111-
| 类别 | 用途说明 | 示例提示词 |
112-
|-------------------|----------------------------------|------------------------------|
113-
| 数据库描述 | 数据库功能特性说明 | db_description |
114-
| 语法指南 | SQL语法参考手册 | syntax_guide |
115-
| 集群管理 | 节点配置与监控指南 | cluster_management |
116-
| 数据迁移 | 数据导入导出规范 | data_migration |
117-
| 性能调优 | 查询优化策略 | performance_tuning |
118-
| 故障排查 | 常见错误解决方案 | troubleshooting |
119-
| 安装部署 | 环境配置指南 | installation |
120-
| DBA模板 | 管理提示词模板 | dba_template |
121-
122-
123-
124-
4\. **非功能性设计**
125-
126-
4.1 **性能设计**
127-
- 连接池复用机制
128-
- 查询超时控制(默认30s)
129-
- 自动LIMIT 20保护
130-
- 批量查询结果分页
131-
132-
4.2 **安全设计**
133-
```mermaid
134-
flowchart TD
135-
A[输入SQL] --> B{语法解析}
136-
B -->|SELECT| C[允许执行]
137-
B -->|SHOW| C
138-
B -->|EXPLAIN| C
139-
B -->|INSERT/UPDATE/DELETE| D[写操作验证]
140-
D --> E[事务日志记录]
141-
B -->|其他| F[拒绝执行]
142-
```
143-
144-
4.3 **错误处理规范**
145-
| 错误代码 | 触发场景 | 处理策略 |
146-
|----------------|---------------------------|------------------------------|
147-
| KWDB-4001 | 语法错误 | 返回具体错误位置 |
148-
| KWDB-4002 | 权限不足 | 中断执行并告警 |
149-
| KWDB-4003 | 连接超时 | 重试机制(最多3次) |
150-
| KWDB-4004 | 资源不存在 | 返回404状态码 |
151-
152-
5\. **部署架构**
153-
154-
```mermaid
155-
flowchart LR
156-
Client[LLM Agent] -->|HTTP SSE| Server1[MCP Server]
157-
Client -->|StdIO| Server2[MCP Server]
158-
Server1 --> KWDB[KaiwuDB Cluster]
159-
Server2 --> KWDB
160-
```
1+
**开务数据库 MCP 服务设计文档 V1.0**
2+
3+
4+
5+
6+
1\. **文档说明**
7+
8+
1.1 **术语与缩写解释**
9+
10+
| 术语 | 说明 |
11+
|-------------|----------------------------------------------------------------------|
12+
| KWDB | 开务数据库(KaiwuDB)的开源版名称 |
13+
| SSE | Server-Sent Events,服务器推送事件协议 |
14+
| MCP | Model Context Protocol,模型上下文协议,用于LLM Agent与外部资源通信 |
15+
| Prompt | 提示词,用于指导AI模型生成特定类型的回应 |
16+
| LLM | Large Language Model,大型语言模型 |
17+
| Agent | 智能代理,能够根据用户输入执行任务的自动化系统 |
18+
| Tool | MCP协议提供的工具,Agent可调用的函数或服务 |
19+
| Resource | MCP协议提供的资源,Agent可查询或订阅的数据 |
20+
21+
22+
2\. **设计概述**
23+
24+
2.1 **架构设计**
25+
26+
```mermaid
27+
flowchart TD
28+
A[MCP协议层] --> B[工具调度器]
29+
A --> C[资源管理器]
30+
B --> D{查询类型判断}
31+
D -->|读操作| E[查询执行引擎]
32+
D -->|写操作| F[事务处理引擎]
33+
E --> G[结果格式化]
34+
F --> G
35+
G --> H[响应生成]
36+
C --> I[数据库元数据]
37+
C --> J[表结构信息]
38+
H --> A
39+
I --> E
40+
J --> E
41+
```
42+
43+
2.2 **核心流程**
44+
- 协议解析:处理MCP标准输入或HTTP SSE请求
45+
- 工具路由:根据工具类型(read/write)分发处理
46+
- 查询预处理:自动添加LIMIT、语法检查
47+
- 连接池管理:维护数据库连接的生命周期
48+
- 结果封装:统一JSON响应格式
49+
50+
3\. **功能设计**
51+
52+
3.1 **外部接口**
53+
54+
3.1.1 **MCP Tools 接口**
55+
```mermaid
56+
flowchart LR
57+
Tool[LLM Agent] -- JSON-RPC --> MCP_Server
58+
subgraph MCP_Server
59+
direction TB
60+
Tool_Dispatcher --> Read_Query
61+
Tool_Dispatcher --> Write_Query
62+
Read_Query --> DB_Conn[连接池]
63+
Write_Query --> DB_Conn
64+
end
65+
```
66+
67+
3.1.2 **接口定义**
68+
1. 读查询工具:
69+
```json
70+
{
71+
"name": "read-query",
72+
"input": {
73+
"sql": "SELECT * FROM table LIMIT 10"
74+
}
75+
}
76+
```
77+
78+
2. 写查询工具:
79+
```json
80+
{
81+
"name": "write-query",
82+
"input": {
83+
"sql": "INSERT INTO table VALUES(...)"
84+
}
85+
}
86+
```
87+
88+
3.2 **MCP Resources**
89+
| 资源类型 | URI格式 | 示例 |
90+
|-------------------------|----------------------------------|-------------------------------|
91+
| 数据库产品信息 | kwdb://product_info | kwdb://product_info/ |
92+
| 数据库元信息 | kwdb://db_info/{database_name} | kwdb://db_info/db_shig |
93+
| 表结构信息 | kwdb://table/{table_name} | kwdb://table/user_profile |
94+
95+
3.3 **Prompt管理架构**
96+
```mermaid
97+
flowchart TD
98+
A[Prompt Markdown文件] --> B[编译时嵌入]
99+
B --> C[运行时缓存]
100+
C --> D[LLM交互接口]
101+
D --> E[动态内容更新]
102+
B -->|版本控制| F[Git仓库]
103+
104+
subgraph 核心组件
105+
C --> G[Prompt缓存管理器]
106+
G --> H[查询处理器]
107+
end
108+
```
109+
110+
3.4 **Prompt分类规范**
111+
| 类别 | 用途说明 | 示例提示词 |
112+
|-------------------|----------------------------------|------------------------------|
113+
| 数据库描述 | 数据库功能特性说明 | db_description |
114+
| 语法指南 | SQL语法参考手册 | syntax_guide |
115+
| 集群管理 | 节点配置与监控指南 | cluster_management |
116+
| 数据迁移 | 数据导入导出规范 | data_migration |
117+
| 性能调优 | 查询优化策略 | performance_tuning |
118+
| 故障排查 | 常见错误解决方案 | troubleshooting |
119+
| 安装部署 | 环境配置指南 | installation |
120+
| DBA模板 | 管理提示词模板 | dba_template |
121+
122+
123+
124+
4\. **非功能性设计**
125+
126+
4.1 **性能设计**
127+
- 连接池复用机制
128+
- 查询超时控制(默认30s)
129+
- 自动LIMIT 20保护
130+
- 批量查询结果分页
131+
132+
4.2 **安全设计**
133+
```mermaid
134+
flowchart TD
135+
A[输入SQL] --> B{语法解析}
136+
B -->|SELECT| C[允许执行]
137+
B -->|SHOW| C
138+
B -->|EXPLAIN| C
139+
B -->|INSERT/UPDATE/DELETE| D[写操作验证]
140+
D --> E[事务日志记录]
141+
B -->|其他| F[拒绝执行]
142+
```
143+
144+
4.3 **错误处理规范**
145+
| 错误代码 | 触发场景 | 处理策略 |
146+
|----------------|---------------------------|------------------------------|
147+
| KWDB-4001 | 语法错误 | 返回具体错误位置 |
148+
| KWDB-4002 | 权限不足 | 中断执行并告警 |
149+
| KWDB-4003 | 连接超时 | 重试机制(最多3次) |
150+
| KWDB-4004 | 资源不存在 | 返回404状态码 |
151+
152+
5\. **部署架构**
153+
154+
```mermaid
155+
flowchart LR
156+
Client[LLM Agent] -->|HTTP SSE| Server1[MCP Server]
157+
Client -->|StdIO| Server2[MCP Server]
158+
Server1 --> KWDB[KaiwuDB Cluster]
159+
Server2 --> KWDB
160+
```

0 commit comments

Comments
 (0)