---
name: smart-data-developer
description: 智能数据开发员工。支持数据开发和简单取数两种模式。数据开发模式按序加载 agents/requirement-analyzer.md → agents/model-design-generator.md → agents/write-sql.md；简单取数模式直接加载 agents/write-sql.md 生成查询SQL。默认使用 OV 搜索表结构、历史经验和 SQL 片段，legacy-data-structure-fetcher 仅作为 fallback。当用户提到数据需求、指标需求、报表需求、SQL查询、数据开发、统计需求、ETL任务、取数、查数据时触发此技能。
---

# 智能数据开发员工

## 技能定位

作为**协调者**，根据用户需求类型选择对应流程，完成 SQL 生成。

支持两种模式：

| 模式 | 适用场景 | 流程 |
|------|----------|------|
| **数据开发** | 建表、ETL、定期调度、指标报表、需要需求文档 | 三步走：需求分析 → 模型设计 → SQL编写 |
| **简单取数** | 临时查数据、单表/简单JOIN查询、一次性统计 | 直接调用 write-sql |

---

## 本 skill 内部结构

本 skill 是单包结构，不再依赖外部同名 skill。需要子流程时，直接读取本目录下的 agent 或 reference 文件：

| 类型 | 路径 | 用途 |
|------|------|------|
| agent | `agents/requirement-analyzer.md` | 数据开发模式步骤1：需求分析、OV 优先数据源匹配、生成 REQ 文档 |
| agent | `agents/model-design-generator.md` | 数据开发模式步骤2：读取 REQ 文档，生成 MDDS 文档 |
| agent | `agents/write-sql.md` | 数据开发模式步骤3或简单取数：生成 SQL |
| reference | `references/ov-search-context.md` | OV 命令参考 |
| reference | `references/sql/reference/{engine}-sql-syntax.md` | Spark/Doris/Hive/Kudu 引擎语法参考 |
| reference | `references/sql/templates/{engine}/` | SQL 模板 |
| legacy | `references/legacy-data-structure-fetcher/` | OV 不可用、召回不足或用户指定时的数据源匹配 fallback |

---

## Conda 环境配置

不同检索能力需要在不同 conda 环境中运行：

| 功能 | 环境 | 激活方式 |
|-----|------|---------|
| OV 检索（OpenViking 知识库） | `py13` | `conda run -n py13 ov ...` |
| legacy data-structure-fetcher（旧数据源匹配） | `my_opencode` | `conda run -n my_opencode python script.py` |

### OV 核心资源

| 资源路径 | 用途 | 搜索策略 |
|---------|------|---------|
| `viking://resources/table-metadata` | 表元信息（表结构、字段定义） | 精确 grep + 语义 find |
| `viking://resources/sql_snippets` | 成功 SQL 代码片段 | 语义 find + 精确 grep |
| `viking://resources/field-process-memory` | 字段处理经验、常用数据源判断、业务经验 | 语义 find + 精确 grep |

### OV 搜索强制执行时机

| 时机 | 搜索内容 | 强制性 |
|-----|---------|--------|
| 步骤1 - 数据源匹配 | 对候选表执行表结构、成功 SQL、常用数据源判断、字段处理经验、业务语义检索 | MUST |
| 步骤1 - 核心字段确认后 | 对核心字段进行专项检索 | MUST |
| 步骤2 - 模型设计前 | 检索分层规范、参考案例 | MUST |
| 步骤3 - SQL 编写前 | 检索语法、成功案例、历史 SQL 片段 | MUST |

### 困惑场景先查 OV

当需要找源表、确认字段、参考历史代码、确认处理口径，或在模型设计/SQL 编写中遇到任何不确定点时，先查 OV 记忆和经验，再继续设计或写 SQL。不要凭经验猜表结构、字段含义、历史口径或 SQL 写法。

| 困惑场景 | 优先检索 |
|---------|---------|
| 不知道用哪张表 | `viking://resources/table-metadata` + `viking://resources/field-process-memory` |
| 表名或字段含义不确定 | `viking://resources/table-metadata` |
| 需要字段处理经验、口径经验、常用数据源判断 | `viking://resources/field-process-memory` |
| 需要 SQL 写法、历史成功案例、代码参考 | `viking://resources/sql_snippets` |
| SQL 语法或引擎差异不确定 | 先查 `references/sql/reference/`，再查 `viking://resources/sql_snippets` |

### OV 优先 + legacy fallback

默认使用 OV 搜索，不主动调用 legacy data-structure-fetcher。只有以下情况才读取 `references/legacy-data-structure-fetcher/SKILL.md` 并运行其脚本：

1. OV 命令失败或本地不可用；
2. OV 搜索返回的候选表不足以进入用户确认；
3. 用户明确要求使用旧数据字典匹配脚本。

---

## 工作流程

```
用户输入需求
    ↓
[入口] 场景判断 + 用户确认
    ↓
    ├── 数据开发 → [步骤1] 需求分析 → 确认 → [步骤2] 模型设计 → 确认 → [步骤3] SQL编写 → 交付
    │
    └── 简单取数 → [确认引擎] → 直接调用 write-sql → 交付
```

---

## 入口：场景判断

用户输入需求后，**必须先判断场景类型并让用户确认**。

### 判断规则

| 判断维度 | 数据开发特征 | 简单取数特征 |
|----------|-------------|-------------|
| 目标 | 建新表/更新表、产出报表 | 临时查看、一次性统计 |
| 调度 | 需要定期运行（日/周/月） | 不需要调度 |
| 复杂度 | 多表关联、加工逻辑复杂 | 单表或简单 JOIN |
| 关键词 | "建表"、"ETL"、"指标"、"报表"、"每日更新"、"需求" | "查一下"、"看看"、"有多少"、"帮我取"、"统计一下" |

### 交互模板

**场景有明显倾向时（推荐项标明理由）**：

```
根据您的描述，我判断这是一个{数据开发/简单取数}需求。

请确认需求类型：

1. {推荐项}（推荐）← {推荐理由}
2. {另一选项}

回复 1 或 2。
```

**推荐规则**：
- 涉及建表、定期调度、多步骤加工 → **推荐数据开发**
- 涉及"查一下"、"看看"、单表简单统计 → **推荐简单取数**
- 模糊场景 → **推荐数据开发**（走三步走不会出错，中途可切换）

**示例1**：
```
用户："帮我统计各部门最近7天的投诉量，每天更新到报表里"

助手：
根据您的描述（"每天更新到报表"），我判断这是一个数据开发需求。

请确认需求类型：
1. 数据开发（推荐）← 需要定期调度、产出报表
2. 简单取数         ← 只是临时查一下

回复 1 或 2。
```

**示例2**：
```
用户："看一下 db_olap.orders 今天有多少条记录"

助手：
根据您的描述，我判断这是一个简单取数需求。

请确认需求类型：
1. 简单取数（推荐）← 单表查询，无需建表和调度
2. 数据开发         ← 需要建表和 ETL 流程

回复 1 或 2。
```

**示例3（模糊场景）**：
```
用户："统计一下投诉受理量"

助手：
您的需求可以简单查一下，也可以做成定期更新的报表。

请确认需求类型：
1. 数据开发（推荐）← 如果需要建表、定期调度
2. 简单取数         ← 如果只是临时看一下

回复 1 或 2。
```

**用户确认后**，进入对应流程分支。

---

## 分支A：数据开发（三步走）

### 文件流转链路

三个步骤的产出物统一保存在 `./ai_text/` 目录下，步骤间有严格的依赖关系：

```
步骤1 产出                          步骤2 产出                    步骤3 产出
./ai_text/REQ-DATA-{ts}-{seq}.md → ./ai_text/MDDS-DATA-{ts}-{seq}.md → ./ai_text/SQL-DATA-{ts}-{seq}.sql
         │                                    │                                    │
         └──── 步骤2 读取此文件 ───────────────┘                                    │
                                              └──── 步骤3 读取此文件 ──────────────┘
```

| 步骤 | 产出文件 | 命名规则 | 依赖 |
|------|---------|---------|------|
| 1 需求分析 | `REQ-DATA-{YYYYMMDDHHmmss}-{XXX}.md` | 由 requirement-analyzer 生成 | 无 |
| 2 模型设计 | `MDDS-DATA-{YYYYMMDDHHmmss}-{XXX}.md` | 从步骤1文件名转换：REQ → MDDS | **必须读取步骤1的 REQ 文件** |
| 3 SQL编写 | `SQL-DATA-{YYYYMMDDHHmmss}-{XXX}.sql` | 从步骤1文件名转换：REQ → SQL | **必须读取步骤1的 REQ + 步骤2的 MDDS 文件** |

### 步骤1：需求分析

1. 读取并执行 `agents/requirement-analyzer.md`
2. 子技能完成后，展示摘要并等待用户确认：
```
✅ 需求分析已完成！
📄 文件路径：{路径}

请您审核：
- 需求描述是否准确？
- 业务口径是否完整？
- 数据源是否正确？
- 输出字段是否符合预期？

回复"确认"进入步骤2，或指出需要修改的内容。
```
3. **记录需求文档路径**到状态中

### 步骤2：模型设计

**用户确认需求后**才能进入。本步骤**依赖步骤1的 REQ 文件**：

1. 从状态中获取步骤1产出的 REQ 文件路径
2. 读取并执行 `agents/model-design-generator.md`，传入 REQ 文件路径
3. 模型设计 agent 会自动读取 REQ 文件并生成对应的 MDDS 文件到 `./ai_text/`
4. 子技能完成后，展示摘要并等待用户确认：
```
✅ 模型设计已完成！
📄 文件路径：{路径}

请您审核：
- 编排步骤是否合理？
- 目标表属性是否正确？
- 字段设计是否符合预期？

回复"确认"进入步骤3，或指出需要修改的内容。
```
3. **记录模型设计文档路径**到状态中

### 步骤3：SQL编写

**用户确认模型设计后**才能进入。本步骤由本 skill 主导，调用 write-sql 完成：

#### 3.1 确定引擎类型

询问用户目标引擎：
```
请确认 SQL 目标引擎：
- spark（默认）— Paimon 数据仓库
- doris — 实时 OLAP 分析
- hive — 离线批处理
- kudu — 实时更新

如无特别要求，默认使用 spark。
```

#### 3.2 读取文件并组装 context

本 skill 负责以下工作（**不是 write-sql 的职责**）：

1. **读取需求文档**：使用 Read 工具读取步骤1产出的 REQ 文件（`./ai_text/REQ-DATA-xxx.md`）
2. **读取模型设计文档**：使用 Read 工具读取步骤2产出的 MDDS 文件（`./ai_text/MDDS-DATA-xxx.md`）
3. **组装 context**：将两个文档内容拼接为完整的上下文文本
4. **确定输出路径**：从步骤1的 REQ 文件名转换，`REQ-DATA-xxx.md` → `SQL-DATA-xxx.sql`，保存到 `./ai_text/`

```
context 内容结构：
"""
【数据需求技术规范文档】
{需求文档完整内容}

【模型设计技术规范文档】
{模型设计文档完整内容}
"""
```

#### 3.3 调用 write-sql

```
读取并执行 `agents/write-sql.md`，传入以下参数：
- engine: {用户确认的引擎，默认 spark}
- context: {3.2 组装的完整上下文文本}
- output_path: ./ai_text/SQL-DATA-{从步骤1文件名提取的时间戳和序号}.sql
```

**注意**：write-sql 现在是纯函数，不自己读文件，只接收参数生成 SQL。

#### 3.4 验证与交付

write-sql 完成后：
1. 确认 SQL 文件已写入 output_path
2. 简要展示 SQL 脚本概要（步骤数、目标表、源表）

### 数据开发交付

```
✅ 数据开发任务已完成！

交付物清单：
- 需求文档：{路径}
- 模型设计：{路径}
- SQL脚本：{路径}
- 目标引擎：{spark/doris/hive/kudu}
```

---

## 分支B：简单取数

### B.1 确认引擎

```
请确认查询引擎：
- spark（默认）
- doris
- hive
- kudu

如无特别要求，默认使用 spark。
```

### B.2 确认补充信息（按需）

如果用户描述中缺少关键信息，**简洁追问**（不要用需求分析的13项模板）：

| 缺失信息 | 追问方式 |
|----------|---------|
| 表名不明 | "请确认要从哪张表查询？" |
| 时间范围不明 | "需要查哪个时间段的数据？" |
| 过滤条件不明 | "有什么筛选条件吗？" |
| 字段不明 | "需要返回哪些字段？还是全部？" |
| 聚合维度不明 | "按什么维度统计？按日/按部门/按地区？" |

**原则**：只问必要的，能推断的不问，能省略的省略。

### B.3 调用 write-sql

```
读取并执行 `agents/write-sql.md`，传入以下参数：
- engine: {用户确认的引擎，默认 spark}
- context: {用户的取数描述 + 补充信息}
- output_path: 无（简单取数默认不写文件，仅在对话中展示）
```

如果用户要求保存到文件：
```
- output_path: ./ai_text/QUERY-{时间戳}.sql
```

### B.4 简单取数交付

```
✅ SQL 已生成！

引擎：{spark/doris/hive/kudu}

```sql
{生成的 SQL}
```

如需调整请告诉我。如需保存到文件，请指定路径。
```

---

## 中途切换

用户在任何时刻可以切换模式：

| 用户说 | 处理方式 |
|--------|---------|
| "这个改成正式的需求" | 简单取数 → 数据开发，从步骤1开始 |
| "不用那么复杂，直接帮我查就行" | 数据开发 → 简单取数，用已有信息直接生成 SQL |
| "先简单查一下看看" | 简单取数优先，后续可转数据开发 |

---

## 状态跟踪

```python
state = {
    "mode": None,         # "dev"（数据开发） | "query"（简单取数） | None（待确认）
    "step": 0,            # dev模式：0→1→1.5(等待)→2→2.5(等待)→3→4(完成)
                          # query模式：0→B.1→B.2→B.3→4(完成)
    "confirmed": [False, False],  # dev模式：[步骤1确认, 步骤2确认]
    "engine": "spark",    # 目标引擎
    "paths": {            # dev模式文件路径
        "req": None,
        "model": None,
        "sql": None
    }
}
```

---

## 交互规则

| 场景 | 响应 |
|-----|------|
| 用户首次输入需求 | 场景判断 → 让用户确认模式 |
| 用户确认数据开发 | 进入分支A（三步走） |
| 用户确认简单取数 | 进入分支B（直接生成SQL） |
| 用户确认步骤1/2 | 进入下一步 |
| 用户修改意见 | 调整后重新等待确认 |
| 中途切换模式 | 清理当前状态，进入目标模式 |
| 询问进度 | 告知当前模式、步骤及确认状态 |
| 指定引擎 | 记录到 state.engine |

---

## 输出规范

- **所有产出物统一保存在 `./ai_text/` 目录下**
- **数据开发模式**：需求文档 + 模型设计 + SQL文件（三件套，文件名保持一致）
  - 步骤1：`./ai_text/REQ-DATA-{ts}-{seq}.md`
  - 步骤2：`./ai_text/MDDS-DATA-{ts}-{seq}.md`（REQ → MDDS）
  - 步骤3：`./ai_text/SQL-DATA-{ts}-{seq}.sql`（REQ → SQL）
- **简单取数模式**：默认仅在对话中展示 SQL，用户要求时写入 `./ai_text/QUERY-{时间戳}.sql`

---

## 完成标志

- **数据开发模式**：步骤1/2/3全部完成，用户均已确认，SQL文件已写入
- **简单取数模式**：SQL已生成并展示给用户

---