Files
smart-data-dev-skill/skills/smart-data-developer/SKILL.md
2026-04-28 10:04:26 +00:00

452 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
name: smart-data-developer
description: 智能数据开发员工。本项目为数据开发专用项目唯一任务是将业务需求转化为可执行SQL。【任何用户消息都必须立即触发此技能】。无论是需求描述、问题咨询、闲聊问候、或其他任何形式的用户输入都应触发此技能启动需求分析→模型设计→SQL编写的工作流程。此技能是本项目的核心入口无例外、无条件触发。
---
# 智能数据开发员工
## 技能定位
按序调用子技能完成端到端数据开发。
| 步骤 | 子技能 | 产出物 |
|-----|--------|--------|
| 1 | requirement-analyzer | 《数据需求技术规范文档》 |
| 2 | model-design-generator | 《模型设计技术规范文档》 |
| 3 | write-sql | 可执行SQL脚本 |
---
## Conda 环境配置
不同子技能和 OV 检索需要在不同 conda 环境中运行:
| 功能 | 环境 | 激活方式 |
|-----|------|---------|
| data-structure-fetcher数据源匹配 | `my_opencode` | `conda run -n my_opencode python script.py` |
| ov 检索OpenViking 知识库) | `py13` | `conda run -n py13 ov ...` |
### conda run 示例
**数据源匹配my_opencode 环境)**
```bash
# 直接使用 conda run 执行 Python 脚本
conda run -n my_opencode python /path/to/data_fetcher_script.py
# 或先激活环境再执行
conda activate my_opencode
python /path/to/data_fetcher_script.py
```
**OV 检索py13 环境)**
```bash
# 精确 grep 搜索表结构
conda run -n py13 ov grep "dim_intnl_org" --uri "viking://resources/table-metadata" --node-limit 5
# 语义 find 搜索成功案例
conda run -n py13 ov find "窗口函数" --uri "viking://resources/sql_snippets" --threshold 0.2
# 读取资源内容
conda run -n py13 ov read viking://resources/sql_snippets/{目录}/{文件}.sql
```
---
## OpenViking 资源库
加载`ov-search-context`技能来查找数据开发相关的资源
### 核心资源
| 资源路径 | 用途 | 搜索策略 |
|---------|------|---------|
| `viking://resources/sql_snippets` | 成功SQL代码片段 | 语义find + 精确grep |
| `viking://resources/table-metadata` | 表元信息(表结构、字段定义) | 精确grep + 语义find |
| `viking://resources/field-process-memory` | 字段处理经验笔记 | 语义find + 精确grep |
### 搜索参数推荐
| 参数 | 推荐值 | 说明 |
|-----|-------|------|
| `--node-limit` | 5-15 | 避免上下文膨胀 |
| `--threshold` | 0.2 | 过滤低相关性结果(语义搜索) |
---
## OV搜索强制执行时机
**为什么必须 OV 搜索**OV 知识库包含历史成功案例、表结构信息、字段处理经验。**不检索会导致**
- 猜测表结构 → 字段选错 → SQL 失败
- 缺乏成功案例参考 → 重复踩坑 → 代码质量差
- 猜测字段含义 → 口径偏差 → 业务错误
- 猜测处理方式 → 维护困难 → 返工成本高
---
**强制触发时机(不可跳过)**
| 时机 | 触发点 | 搜索内容 | 强制性 | 检索数量 |
|-----|--------|---------|--------|---------|
| 步骤1 - 数据源匹配后 | data-structure-fetcher 返回源表列表后 | **③ 常用数据源判断(最优先)** + 每个推荐表执行 5 类检索表结构、成功SQL、常用判断、字段处理经验、业务语义 | ✅ MUST | 每表 5 次 |
| 步骤1 - 核心字段确认后 | 用户确认核心字段时 | 对核心字段进行专项检索 | ✅ MUST | 每字段 3 次 |
| 步骤2 - 模型设计前 | 用户确认需求后,开始模型设计 | OV 检索分层规范、参考案例 | ✅ MUST | 2-3 次 |
| 步骤3 - SQL 编写前 | 用户确认模型设计后,开始编写 SQL | OV 检索语法、成功案例 | ✅ MUST | 3-5 次 |
---
**数据源匹配后的具体检索内容**
| 检索类型 | 目的 | 命令py13 环境) | 优先级 |
|---------|------|-----------------|--------|
| ③ 常用数据源判断 | **判断是否为常用数据源**(历史使用频率、稳定性) | `conda run -n py13 ov grep "{表名}" --uri "viking://resources/field-process-memory" --node-limit 10` | **最高(立即执行)** |
| ① 表结构检索 | 确认字段定义 | `conda run -n py13 ov grep "{表名}" --uri "viking://resources/table-metadata" --node-limit 10` | 高 |
| ② 成功SQL检索 | 找历史代码案例 | `conda run -n py13 ov grep "{表名}" --uri "viking://resources/sql_snippets" --node-limit 15` | 高 |
| ④ 字段处理经验 | 了解处理方式 | `conda run -n py13 ov grep "{表名}.*{字段}" --uri "viking://resources/field-process-memory" --node-limit 10` | 中 |
| ⑤ 业务语义检索 | 业务使用经验 | `conda run -n py13 ov find "{表名} {业务}" --uri "viking://resources/field-process-memory" --threshold 0.2` | 中 |
---
**困惑场景(立即检索)**
- 表名陌生 → 立刻 `conda run -n py13 ov grep "{表名}" --uri "viking://resources/table-metadata"`
- 字段歧义 → 立刻 `conda run -n py13 ov grep "{表名}.*{字段}" --uri "viking://resources/table-metadata"`
- 语法不确定 → 立刻 `conda run -n py13 ov find "{语法}" --uri "viking://resources/sql_snippets" --threshold 0.2`
- 找不到成功案例 → 立刻 `conda run -n py13 ov find "{业务场景}" --uri "viking://resources/sql_snippets" --threshold 0.2`
---
## OV命令速查
**注意OV 检索需要在 `py13` conda 环境中运行,使用 `conda run -n py13 ov ...`**
```bash
# === 精确grep定位具体表/字段 ===
用表名搜索:
conda run -n py13 ov grep "{表名}" --uri "viking://resources/table-metadata" --node-limit 5
表名加字段名组合搜索:
conda run -n py13 ov grep "dim_intnl_org.*org_id" --uri viking://resources/table-metadata -n 5
多表名 OR 搜索:
conda run -n py13 ov grep "table1|table2|table3" --uri viking://resources/table-metadata -n 5
# === 语义find召回相关内容 ===
conda run -n py13 ov find "{业务概念}" --uri "viking://resources/sql_snippets" --threshold 0.2
conda run -n py13 ov find "{问题描述}" --uri "viking://resources/field-process-memory" --threshold 0.2
# === 使用源表信息搜索成功案例 ===
conda run -n py13 ov grep "{源表表名}" --uri "viking://resources/sql_snippets" --node-limit 10
conda run -n py13 ov grep "{源表表名}.*{字段}" --uri "viking://resources/field-process-memory" --node-limit 10
conda run -n py13 ov find "{字段名} 问题描述" --uri "viking://resources/field-process-memory" --node-limit 5
# === 读取内容 ===
conda run -n py13 ov overview viking://resources/table-metadata/{表名}
conda run -n py13 ov read viking://resources/sql_snippets/{目录}/{文件}.sql
conda run -n py13 ov read viking://resources/field-process-memory/{文件}.md
```
---
## 工作流程
```
步骤1需求分析 → 调用 requirement-analyzer + 数据源匹配的同时进行OV检索 + 困惑时OV检索
步骤2模型设计 → 调用 model-design-generator + 困惑时OV检索
步骤3SQL编写 → 调用 write-sql + 困惑时OV检索
交付完成
```
---
## 执行流程详细步骤
### 步骤1需求分析
**执行前检查**:无(直接开始)。
调用 `skill(name="requirement-analyzer")`
**困惑时检索py13 环境)**
- 不熟悉业务概念 → `conda run -n py13 ov find "{概念}" --uri "viking://resources/field-process-memory" --threshold 0.2`
- 不确定指标口径 → `conda run -n py13 ov find "{指标名称} 口径" --uri "viking://resources/field-process-memory" --threshold 0.3`
**完成后衔接**`📄 已保存:{路径}。需求分析完成,开始模型设计...`
#### ✅ MUST数据源匹配后 OV 深度检索
**强制性说明**data-structure-fetcher 返回推荐数据源后,**必须对每个推荐表进行全方位 OV 检索**。不检索会导致:
- 猜测表结构 → 字段选错 → SQL 失败
- 缺乏成功案例参考 → 重复踩坑 → 代码质量差
- 不了解字段处理经验 → 口径偏差 → 业务错误
---
**触发时机**requirement-analyzer 模块3data-structure-fetcher 返回推荐表列表后,立即执行
**执行环境**py13 conda 环境,使用 `conda run -n py13 ov ...`
---
**检索策略:每个推荐表必须执行以下 5 类检索**
| 检索类型 | 目的 | 命令模板 | node-limit |
|---------|------|---------|------------|
| ① 表结构检索 | 确认表字段定义、数据类型 | `conda run -n py13 ov grep "{表名}" --uri "viking://resources/table-metadata"` | 5-10 |
| ② 成功SQL案例检索 | 查找该表的历史成功 SQL 代码 | `conda run -n py13 ov grep "{表名}" --uri "viking://resources/sql_snippets"` | 10-15 |
| ③ 常用数据源判断 | **判断该表是否为常用数据源**(历史使用频率、稳定性、推荐度) | `conda run -n py13 ov grep "{表名}" --uri "viking://resources/field-process-memory"` | 5-10 |
| ④ 字段处理经验检索 | 了解该表字段的常见处理方式、注意事项 | `conda run -n py13 ov grep "{表名}.*{字段名}" --uri "viking://resources/field-process-memory"` | 5-10 |
| ⑤ 业务语义检索 | 了解该表在业务场景中的使用经验 | `conda run -n py13 ov find "{表名} {业务场景}" --uri "viking://resources/field-process-memory" --threshold 0.2` | 5-10 |
---
**③ 常用数据源判断 - 详细说明**
这是数据源匹配后**必须立即执行**的关键检索,用于判断推荐表是否值得采用:
**执行时机**data-structure-fetcher 返回推荐表后,**立即执行此检索**
**检索命令**
```bash
conda run -n py13 ov grep "{表名}" --uri "viking://resources/field-process-memory" --node-limit 10
```
**判断标准**
| 检索结果 | 判断 | 建议操作 |
|---------|------|---------|
| 有多条历史使用记录≥3条 | ✅ **常用数据源** | 推荐优先采用,可参考历史处理经验 |
| 有少量记录1-2条 | ⚠️ **偶尔使用** | 可采用,需谨慎验证字段逻辑 |
| 无检索结果 | ❓ **新/陌生数据源** | 需进一步验证表结构,或寻找替代表 |
| 有警告/问题记录 | ⚠️ **有风险** | 需评估问题严重性,考虑替代方案 |
**结果展示格式**
```
📋 常用数据源判断结果:
【dwd_crm_srv_complaint_rt】
- 检索结果:找到 5 条历史使用记录
- 判断:✅ 常用数据源(推荐采用)
- 历史使用场景:投诉量统计、投诉处理时效、部门投诉排名
- 注意事项create_org_id 需关联组织表获取部门名称
【dim_intnl_org_new】
- 检索结果:找到 8 条历史使用记录
- 判断:✅ 常用数据源(高频使用)
- 历史使用场景:组织维度统计、部门层级分析、归属地统计
- 注意事项org_name 有多级命名,需按业务口径标准化
```
**决策建议**
- 多个推荐表中,优先选择"常用数据源"
- 对"陌生数据源"需额外验证,或向用户确认是否采用
- 对"有风险"数据源,建议告知用户并提供替代方案
---
**具体执行流程py13 环境)**
```bash
# 对每个推荐表dwd_crm_srv_complaint_rt依次执行
# ① 表结构检索(确认字段)
conda run -n py13 ov grep "dwd_crm_srv_complaint_rt" --uri "viking://resources/table-metadata" --node-limit 10
# ② 成功SQL案例检索找历史代码
conda run -n py13 ov grep "dwd_crm_srv_complaint_rt" --uri "viking://resources/sql_snippets" --node-limit 15
# ③ 常用数据源判断(判断是否常用 - 数据源匹配后立即执行)
conda run -n py13 ov grep "dwd_crm_srv_complaint_rt" --uri "viking://resources/field-process-memory" --node-limit 10
# ④ 字段处理经验检索(找处理笔记 - 对核心字段)
conda run -n py13 ov grep "dwd_crm_srv_complaint_rt.complaint_id" --uri "viking://resources/field-process-memory" --node-limit 10
# ⑤ 业务语义检索(结合业务场景)
conda run -n py13 ov find "dwd_crm_srv_complaint_rt 投诉统计" --uri "viking://resources/field-process-memory" --threshold 0.2 --node-limit 10
```
**执行顺序建议**
- ③ 常用数据源判断是**最优先执行**的检索,应在数据源匹配后立即执行
- 其他检索可根据常用数据源判断结果调整执行优先级
---
**检索结果利用**
检索完成后,必须:
1. **汇总展示**:将检索结果整理成摘要,展示给用户
```
📊 OV 检索结果摘要:
【dwd_crm_srv_complaint_rt】
- 常用数据源:✅ 常用(找到 5 条历史使用记录)
- 表结构:包含 complaint_id、create_org_id、assist_dept_org_id 等字段
- 成功案例:找到 3 个历史 SQL投诉量统计、投诉处理时效分析
- 处理经验create_org_id 字段需关联组织架构表获取部门名称
【dim_intnl_org_new】
- 常用数据源:✅ 常用(找到 8 条历史使用记录)
- 表结构:包含 org_id、org_name、accnt_bureau 等字段
- 成功案例:找到 5 个历史 SQL部门维度统计
- 处理经验org_name 有多级命名规范,需按业务口径标准化
【dwd_new_table_2024】
- 常用数据源:❓ 陌生数据源(无历史使用记录)
- 建议:需进一步验证表结构,或寻找更成熟的替代表
```
2. **辅助源表选择**:基于常用数据源判断和成功案例数量,建议用户优先选择哪些表
```
建议:
- ✅ 优先采用dwd_crm_srv_complaint_rt常用数据源有 3 个成功案例,历史使用稳定)
- ✅ 优先采用dim_intnl_org_new常用数据源高频使用组织表标准参考
- ⚠️ 需验证dwd_new_table_2024陌生数据源建议先验证或寻找替代表
```
3. **预加载到上下文**:检索到的成功案例和字段处理经验,需在后续模型设计和 SQL 编写时引用
---
**检索时机强制触发表**
| 时间点 | 触发条件 | 检索内容 | 强制性 |
|-------|---------|---------|--------|
| data-structure-fetcher 返回后 | 推荐表列表返回 | **③ 常用数据源判断(最优先)** + 每个表的 5 类检索 | ✅ MUST |
| 用户补充新表名时 | 用户提及陌生表名 | 立刻 OV 检索该表(优先执行常用数据源判断) | ✅ MUST |
| 用户询问字段含义时 | 用户对字段有疑问 | OV grep 该表.字段 | ✅ MUST |
| 发现字段歧义时 | 同一字段有多来源 | OV find 语义检索 | ✅ MUST |
| 陌生数据源判断后 | 无历史使用记录 | 额外验证表结构,或建议替代表 | ✅ MUST |
---
**并行检索策略**
为提高效率,对多个推荐表的检索可并行执行:
```bash
# 并行检索多个表(使用 task agent 或 bash 后台)
conda run -n py13 ov grep "table1" --uri "viking://resources/table-metadata" --node-limit 10 &
conda run -n py13 ov grep "table2" --uri "viking://resources/table-metadata" --node-limit 10 &
conda run -n py13 ov grep "table3" --uri "viking://resources/table-metadata" --node-limit 10 &
```
---
**关键字段专项检索**
当推荐表中包含**核心业务字段**时,必须额外进行字段级检索:
```bash
# 对核心字段complaint_id、org_id进行专项检索
conda run -n py13 ov grep "dwd_crm_srv_complaint_rt.complaint_id" --uri "viking://resources/table-metadata" --node-limit 5
conda run -n py13 ov grep "complaint_id" --uri "viking://resources/field-process-memory" --node-limit 10
conda run -n py13 ov find "complaint_id 去重计数" --uri "viking://resources/sql_snippets" --threshold 0.2 --node-limit 10
```
---
### 步骤2模型设计
**执行前检查**:需求分析已完成,用户已确认需求。
调用 `skill(name="model-design-generator")`
**困惑时检索py13 环境)**
- 确认表结构 → `conda run -n py13 ov grep "{表名}" --uri "viking://resources/table-metadata"`
- 了解分层规范 → `conda run -n py13 ov find "分层架构 DWA DWM ADS" --uri "viking://resources/sql_snippets" --threshold 0.2`
**完成后衔接**`📄 已保存:{路径}。下一步将编写SQL脚本。请确认以上设计是否正确。`
---
### 步骤3SQL编写
**执行前检查**:用户已确认模型设计。
调用 `skill(name="write-sql")`
**困惑时检索py13 环境)**
- SQL语法 → `conda run -n py13 ov find "{语法} 用法" --uri "viking://resources/sql_snippets" --threshold 0.2`
- 窗口函数示例 → `conda run -n py13 ov find "窗口函数 over partition" --uri "viking://resources/sql_snippets" --threshold 0.2`
**完成后衔接**
```
📄 已保存:{路径}
交付物:
- 需求文档:{路径}
- 模型设计:{路径}
- SQL脚本{路径}
```
---
## 状态跟踪
- step 1: 需求分析完成 → 准备模型设计
- step 2: 模型设计完成 → 等待用户确认
- step 3: SQL编写完成
- step 4: 全流程完成
记录产出物路径需求文档、模型设计文档、SQL脚本。
---
## 交互规则
| 场景 | 响应 |
|-----|------|
| 用户确认 | 进入下一步 |
| 用户修改意见 | 调整后重新等待确认 |
| 中途修改 | 回到对应步骤重新执行 |
| 用户提及陌生概念 | 先OV检索再回复提供选项 |
---
## 交互工具
在需要补充和确认信息,检查和修改的时候,使用`question`工具提供选项供用户选择,例如下面的情况:
```
例如下面的情况,请使用`question`工具:
请补充/确认以下信息:
1. 输出表中文名称:建议为"设备流量通话短信月均使用情况表",是否需要修改?
2. 输出表英文名称:请提供库名.表名db_eda_xxx_prd.ads_device_usage_avg_6m
3. 数据目录:请提供数据目录路径(如:上海电信/大数据中心-xxx团队/xxx应用层
4. 业务口径细节确认:
- "近6个月"的具体时间范围是指从当月向前推6个月即统计月及之前5个月共6个月
- "平均值"计算方式是计算每个设备在这6个月的平均值还是其他口径
- 设备标识字段是什么设备号、用户ID、手机号等
请确认或补充以上信息确认后进入模块3数据源匹配
```
```
请检查并修改:
- 字段是否完整?需要补充或删除哪些字段?
- 字段名称是否需要调整?
- 字段加工逻辑是否准确?来源表.字段是否正确?
- 负责人信息是否正确?
```
---
## 困惑场景检索策略
**注意:所有 OV 检索命令需在 py13 conda 环境中运行**
| 困惑类型 | 检索资源 | 命令 |
|---------|---------|------|
| 不清楚表结构 | table-metadata | `conda run -n py13 ov grep "{表名}" --uri "viking://resources/table-metadata"` |
| 不确定字段含义 | table-metadata | `conda run -n py13 ov grep "{表名}.*{字段名}" --uri "viking://resources/table-metadata"` 或者 `conda run -n py13 ov grep "{字段名}" --uri "viking://resources/table-metadata"` |
| 不熟悉业务概念 | sql_snippets + field-process-memory | `conda run -n py13 ov find "{概念}" --uri "viking://resources/resources/field-process-memory" --threshold 0.2` |
| 需要代码参考 | sql_snippets + field-process-memory | `conda run -n py13 ov find "{功能}" --uri "viking://resources/sql_snippets" --threshold 0.2` |
| 找表成功案例 | sql_snippets + field-process-memory | 分别使用 `conda run -n py13 ov grep` 和 `conda run -n py13 ov find` 搜索两个资源 |
---
## 完成标志
三步骤完成(需求分析 → 模型设计 → SQL编写用户已知交付物位置。