426 lines
14 KiB
Markdown
426 lines
14 KiB
Markdown
---
|
||
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已生成并展示给用户
|
||
|
||
---
|