Files
2026-05-12 07:43:35 +00:00

25 KiB
Raw Permalink Blame History

name, description
name description
smart-data-developer 智能数据开发员工v3。支持数据开发和简单取数两种模式。数据开发模式按序调用 requirement-analyzer → model-design-generator → write-sql 三技能,结合 OV 知识库检索保障质量;简单取数模式直接调用 write-sql 生成查询SQL。当用户提到数据需求、指标需求、报表需求、SQL查询、数据开发、统计需求、ETL任务、取数、查数据时触发此技能。

智能数据开发员工 v3

技能定位

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

支持两种模式:

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

# 直接使用 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 环境)

# 精确 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 失败
  • 缺乏成功案例参考 → 重复踩坑 → 代码质量差
  • 猜测字段含义 → 口径偏差 → 业务错误
  • 猜测处理方式 → 维护困难 → 返工成本高

注意OV 检索仅在数据开发模式分支A中强制执行。简单取数模式按需检索。


强制触发时机(不可跳过,仅数据开发模式)

时机 触发点 搜索内容 强制性 检索数量
步骤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 ...

# === 精确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] 需求分析(+OV检索 → 确认 → [步骤2] 模型设计(+OV检索 → 确认 → [步骤3] SQL编写+OV检索 → 交付
    │
    └── 简单取数 → [确认引擎] → 直接调用 write-sql → 交付

入口:场景判断

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

判断规则

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

交互模板

场景有明显倾向时(推荐项标明理由)

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

请确认需求类型:

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. 调用 skill(name="requirement-analyzer")
  2. 子技能完成后,展示摘要并等待用户确认:
✅ 需求分析已完成!
📄 文件路径:{路径}

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

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

MUST数据源匹配后 OV 深度检索

强制性说明data-structure-fetcher 返回推荐数据源后,必须对每个推荐表进行全方位 OV 检索

触发时机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

③ 常用数据源判断 - 详细说明

这是数据源匹配后必须立即执行的关键检索,用于判断推荐表是否值得采用:

检索命令

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 有多级命名,需按业务口径标准化

决策建议

  • 多个推荐表中,优先选择"常用数据源"
  • 对"陌生数据源"需额外验证,或向用户确认是否采用
  • 对"有风险"数据源,建议告知用户并提供替代方案

并行检索策略

为提高效率,对多个推荐表的检索可并行执行:

# 并行检索多个表(使用 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 &

关键字段专项检索

当推荐表中包含核心业务字段时,必须额外进行字段级检索:

# 对核心字段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

检索结果利用

检索完成后,必须:

  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 编写时引用


困惑时检索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

步骤2模型设计

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

  1. 从状态中获取步骤1产出的 REQ 文件路径
  2. 调用 skill(name="model-design-generator"),传入 REQ 文件路径
  3. 模型设计 skill 会自动读取 REQ 文件并生成对应的 MDDS 文件到 ./ai_text/
  4. 子技能完成后,展示摘要并等待用户确认:
✅ 模型设计已完成!
📄 文件路径:{路径}

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

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

困惑时检索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

步骤3SQL编写

用户确认模型设计后才能进入。本步骤由本 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.mdSQL-DATA-xxx.sql,保存到 ./ai_text/
context 内容结构:
"""
【数据需求技术规范文档】
{需求文档完整内容}

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

3.3 调用 write-sql

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

注意write-sql 是纯函数,不自己读文件,只接收参数生成 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

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

调用 write-sql 时传入以下参数:
- 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
用户提及陌生概念 先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 grepconda run -n py13 ov find 搜索两个资源

输出规范

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

完成标志

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