---
name: data-structure-fetcher
description: 通过文本实体匹配→向量检索→大模型加权汇总三步流程，从数据字典库中智能匹配业务需求所需的数据源及字段。当用户需要了解数据结构、查找表字段、查询数据字典或询问有哪些数据可用时，使用此技能。
---

# 数据结构获取 Skill

## 技能描述

采用**三步匹配流程**，直接调用脚本获取数据源：
1. **向量检索**：调用 `embedding_api_call.py`，传入用户完整问题
2. **文本实体匹配**：从问题中提取核心实体，对**每个实体**依次调用 `wenben_api_call.py`
3. **加权汇总**：解析两份结果 → 加权融合（向量 0.6 + 文本 0.4）→ 输出推荐 Top 5 表

## 目录结构

```
data-structure-fetcher/
├── SKILL.md
└── scripts/
    ├── embedding_api_call.py      # 向量检索脚本
    └── wenben_api_call.py # 文本匹配脚本
```

## 使用方法

### 步骤 1：提取查询实体

从用户问题中提取核心业务实体/关键词。例如：
- "统计各投诉处理部门的投诉受理量" → 提取："投诉"、"部门"、"受理量"

### 步骤 2：调用向量检索（一次）

```bash
python /root/.config/opencode/skills/data-structure-fetcher/scripts/embedding_api_call.py "用户完整问题" 10
```

### 步骤 3：调用文本匹配（每个实体依次调用）

```bash
python /root/.config/opencode/skills/data-structure-fetcher/scripts/wenben_api_call.py "实体1" 5
python /root/.config/opencode/skills/data-structure-fetcher/scripts/wenben_api_call.py "实体2" 5
# ... 每个实体依次调用
```

**注意**：所有实体的返回结果需**合并去重**，作为文本匹配的总结果。

### 步骤 4：解析脚本返回结果

两个脚本均返回 **Markdown 表格格式**，需从中提取结构化信息：
- **向量检索结果**：包含 `distance` 字段（相似度，越小越匹配）
- **文本匹配结果**：不包含 `distance` 字段

每个结果包含：
- `ID`：库名.表名（如 `db_dwd.dwd_crm_srv_complaint_rt`）
- `元数据`：JSON 格式，含 `schema_name`、`table_name`、`table_cn_name`、`table_comment`、`table_owner`、`field_count`
- `文档内容`：字段清单，格式如 `字段名(类型)、字段中文名、...`

### 步骤 5：加权融合排序

```
综合得分 = 向量归一化得分 × 0.6 + 文本归一化得分 × 0.4
```

- **向量得分**：`score = 1 - distance`，然后 min-max 归一化到 [0,1]
- **文本得分**：按命中顺序归一化（首次出现得分最高）
- **来源标记**：
  - `both` — 两个源都命中（★ 最高置信度）
  - `vector_only` — 仅向量命中（□）
  - `text_only` — 仅文本命中（□）

### 步骤 6：输出 Top 5 推荐表

```
================================================================================
📊 推荐数据源 Top 5
================================================================================

★ 1. db_dwd.dwd_crm_srv_complaint_rt
   中文名：投诉整合层主表
   表注释：投诉业务整合宽表
   综合得分：0.9200
   来源：both (向量=0.950, 文本=0.875)
   负责人：蒋平川

□ 2. db_dwa.dwa_crm_base_sr_compln_3rd
   中文名：投诉三级延伸全量宽表
   综合得分：0.8000
   来源：vector_only (向量=0.820, 文本=0.000)
   负责人：郭鑫超

================================================================================
```

## 触发指令

- "查找相关表"、"推荐数据源"、"这个指标用哪些表"
- "查询数据结构"、"有哪些表可以统计 XX"
- "需要了解数据结构"、"查找表字段"、"查询数据字典"

## 被 requirement-analyzer 调用

当 `requirement-analyzer` 进入模块 3（数据源匹配）时，自动调用本 skill，按上述流程执行脚本并汇总结果。