AI agent skill · by @apconw

Schema Exploration

用于发现和理解数据库结构、表、列和关系，支持 M-Schema 格式输出，智能表过滤

Archived 2026-10-23 · Source updated 2026-08-30. Check the original repository for the latest version.

SKILL.md instructions

# 架构探索技能

## 何时使用此技能

当您需要以下操作时使用此技能：
- 理解数据库结构
- 查找包含特定类型数据的表
- 发现列名和数据类型
- 映射表之间的关系
- 为 SQL 生成准备 M-Schema 格式的结构信息
- 回答诸如"有哪些表可用？"或"Customer 表有哪些列？"等问题

## 工作流程

### 1. 列出所有表

使用 `sql_db_list_tables` 工具查看数据库中所有可用的表。

这将返回您可以查询的完整表列表。

### 2. 智能表过滤（针对复杂查询）

当数据库表较多时，不要盲目获取所有表的 schema，而是先进行智能过滤：

1. **获取表列表后**，根据用户问题进行语义分析，提取关键实体和意图
2. **匹配策略**：
   - 将关键词与表名、表注释进行语义匹配（如"销售额" → 可能涉及 orders、sales、products 等表）
   - 考虑表之间的潜在关联（如用户问"客户订单"，需要同时选中 customers 和 orders）
   - 忽略明显无关的系统表、日志表、临时表
3. **输出**：筛选后的相关表名列表（通常 3-8 张表）

**内部思考模板：**
```
用户问题：{user_question}

数据库所有表：
- {table1}, {table2}, ...

任务：从上述表中选出与用户问题直接相关的表。
考虑因素：
1. 表名是否与问题中的实体/指标匹配
2. 是否需要关联表来补充维度信息
3. 忽略明显无关的系统表、日志表

选出的相关表：[table1, table2, ...]
```

### 3. 获取特定表的架构

使用 `sql_db_schema` 工具配合表名来检查：
- **列名** - 有哪些字段可用
- **数据类型** - INTEGER, TEXT, DATETIME 等
- **示例数据** - 示例数据以了解内容
- **主键** - 行的唯一标识符
- **外键** - 与其他表的关系
- **列注释** - 字段含义说明

**提示**：可以一次传入多个表名（逗号分隔），减少工具调用次数。

### 4. 获取表关系

使用 `sql_db_table_relationship` 工具获取表之间的外键/关联关系：
- **关联字段** - 两表通过哪些字段关联
- **JOIN 条件** - 返回格式如 `t_orders.customer_id = t_customers.id`

示例调用：
```
sql_db_table_relationship("t_orders, t_customers, t_products")
```

如果未配置表关系，可以通过以下方式推断：
- 查找以 "Id" 或 "_id" 结尾的列（例如，customer_id, product_id）
- 外键列名通常对应另一个表的主键
- 记录父子关系

### 5. 生成 M-Schema 格式（用于 SQL 生成）

当需要将 schema 信息传递给后续 SQL 生成步骤时，使用 M-Schema 格式组织信息：

```
【DB_ID】 {db_name}
【Schema】
# Table: {table_name}, {table_comment}
[
  ({column_name}:{column_type}, {column_comment}),
]
{foreign_key_1}
{foreign_key_2}
```

**数据库特定规则：**
- PostgreSQL/Oracle/SQL Server: 使用 `schema.table_name` 格式
- MySQL/ClickHouse/SQLite: 使用纯 `table_name`

**引号规则：**
| 数据库类型 | 引号 |
|-----------|------|
| MySQL | \`反引号\` |
| PostgreSQL | "双引号" |
| SQLite | "双引号" |
| SQL Server | [方括号] |
| Oracle | "双引号" |
| ClickHouse | "双引号" |

### 6. 回答问题

提供清晰的信息：
- 可用表及其用途
- 列名及其包含的内容
- 表之间的关联方式
- 示例数据以说明内容

## 示例："有哪些表可用？"

**步骤 1：** 使用 `sql_db_list_tables`

**响应：**
```
数据库包含多个表：
1. Customer - 存储客户信息
2. Employee - 存储员工信息
3. Invoice - 客户购买记录
4. InvoiceLine - 发票中的单个项目
...
```

## 示例："这些表之间有什么关系？"

**步骤 1：** 使用 `sql_db_table_relationship("Customer, Invoice, InvoiceLine")`

**响应：**
```
表之间的关系如下：
  • Invoice.CustomerId = Customer.Id
  • InvoiceLine.InvoiceId = Invoice.Id

✅ 表关系已获取完成。
```

## 示例："准备查询销售额数据的 M-Schema"

**步骤 1：** `sql_db_list_tables` → 智能过滤出 orders, products, customers
**步骤 2：** `sql_db_schema("orders, products, customers")` → 获取完整 schema
**步骤 3：** `sql_db_table_relationship("orders, products, customers")` → 获取关系
**步骤 4：** 组织为 M-Schema 格式：

```
【DB_ID】 sales_db
【Schema】
# Table: orders, 订单表
[
  (id:INTEGER, 订单ID),
  (customer_id:INTEGER, 客户ID),
  (product_id:INTEGER, 产品ID),
  (amount:DECIMAL, 订单金额),
  (order_date:DATETIME, 下单时间),
]
orders.customer_id = customers.id
orders.product_id = products.id

# Table: products, 产品表
[
  (id:INTEGER, 产品ID),
  (name:VARCHAR, 产品名称),
  (category:VARCHAR, 产品类别),
  (price:DECIMAL, 单价),
]

# Table: customers, 客户表
[
  (id:INTEGER, 客户ID),
  (name:VARCHAR, 客户名称),
  (region:VARCHAR, 所属区域),
]
```

## 质量指南

**对于"列出表"问题：**
- 显示所有表名
- 添加每个表包含内容的简要描述
- 对相关表进行分组（例如，交易、人员）

**对于"描述表"问题：**
- 列出所有列及其数据类型
- 解释每列包含的内容
- 显示示例数据以提供上下文
- 注明主键和外键
- 解释与其他表的关系

**对于"如何查询 X"问题：**
- 识别所需的表
- 映射 JOIN 路径
- 解释关系链
- 建议下一步（使用查询编写技能）

**对于复杂查询准备：**
- 使用智能表过滤，只选相关表
- 生成 M-Schema 格式供 SQL 生成使用
- 明确标注表关系和 JOIN 条件

## 常见探索模式

### 模式 1：查找表
"哪个表包含客户信息？"
→ 使用 list_tables，然后描述 Customer 表

### 模式 2：理解结构
"Invoice 表中有什么？"
→ 使用 schema 工具显示列和示例数据

### 模式 3：映射关系
"客户如何与发票关联？"
→ 使用 `sql_db_table_relationship("Customer, Invoice, InvoiceLine")` 获取关系

### 模式 4：查询准备
"我要分析各产品销售情况"
→ 智能过滤 → 获取 schema → 获取关系 → 输出 M-Schema

## 提示

- 外键通常以 "Id" 结尾，并匹配表名
- 使用示例数据了解值的格式
- 不确定使用哪个表时，先列出所有表
- 获取 schema 时尽量一次传入多个相关表名，减少工具调用
- M-Schema 格式有助于后续 SQL 生成的准确性