15 KiB
15 KiB
name, description
| name | description |
|---|---|
| smart-data-developer | 智能数据开发员工。支持数据开发和简单取数两种模式。数据开发模式按序加载 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/field-process-memory |
字段处理经验、常用数据源判断、业务经验 | 优先检索：语义 find + 精确 grep |
viking://resources/table-metadata |
表元信息（表结构、字段定义） | 精确 grep + 语义 find |
viking://resources/sql_snippets |
成功 SQL 代码片段 | 语义 find + 精确 grep |
运行任何 OV 命令之前，先读取相关 reference，默认先看 references/ov-search-context.md 确认命令用法；涉及 SQL 引擎语法时，再看 references/sql/reference/{engine}-sql-syntax.md。
OV 搜索强制执行时机
| 时机 | 搜索内容 | 强制性 |
|---|---|---|
| 步骤1 - 数据源匹配 | 对候选表执行表结构、成功 SQL、常用数据源判断、字段处理经验、业务语义检索 | MUST |
| 步骤1 - 核心字段确认后 | 对核心字段进行专项检索 | MUST |
| 步骤2 - 模型设计前 | 检索分层规范、参考案例 | MUST |
| 步骤3 - SQL 编写前 | 检索语法、成功案例、历史 SQL 片段 | MUST |
困惑场景先查 OV
当需要找源表、确认字段、参考历史代码、确认处理口径，或在模型设计/SQL 编写中遇到任何不确定点时，先查 OV 记忆和经验，再继续设计或写 SQL。不要凭经验猜表结构、字段含义、历史口径或 SQL 写法。
| 困惑场景 | 优先检索 |
|---|---|
| 不知道用哪张表 | 先查 viking://resources/field-process-memory，再查 viking://resources/table-metadata |
| 表名或字段含义不确定 | 先查 viking://resources/field-process-memory，再查 viking://resources/table-metadata |
| 需要字段处理经验、口径经验、常用数据源判断 | viking://resources/field-process-memory |
| 需要 SQL 写法、历史成功案例、代码参考 | 先查 viking://resources/field-process-memory 判断业务口径，再查 viking://resources/sql_snippets |
| SQL 语法或引擎差异不确定 | 先查 references/sql/reference/，再查 viking://resources/sql_snippets |
OV 优先 + legacy fallback
默认使用 OV 搜索，不主动调用 legacy data-structure-fetcher。只有以下情况才可以考虑 legacy fallback，且必须先告知用户原因并获得明确同意，再读取 references/legacy-data-structure-fetcher/SKILL.md 并运行其脚本：
- OV 命令失败或本地不可用；
- OV 搜索返回的候选表不足以进入用户确认；
- 用户明确要求使用旧数据字典匹配脚本。
告知模板：
OV 检索结果不足/不可用。是否同意我使用 legacy data-structure-fetcher 脚本补充搜索数据源？
工作流程
用户输入需求
↓
[入口] 场景判断 + 用户确认
↓
├── 数据开发 → [步骤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：需求分析
- 读取并执行
agents/requirement-analyzer.md - 子技能完成后，展示摘要并等待用户确认：
✅ 需求分析已完成！
📄 文件路径：{路径}
请您审核：
- 需求描述是否准确？
- 业务口径是否完整？
- 数据源是否正确？
- 输出字段是否符合预期？
回复"确认"进入步骤2，或指出需要修改的内容。
- 记录需求文档路径到状态中
步骤2：模型设计
用户确认需求后才能进入。本步骤依赖步骤1的 REQ 文件：
- 从状态中获取步骤1产出的 REQ 文件路径
- 读取并执行
agents/model-design-generator.md，传入 REQ 文件路径 - 模型设计 agent 会自动读取 REQ 文件并生成对应的 MDDS 文件到
./ai_text/ - 子技能完成后，展示摘要并等待用户确认：
✅ 模型设计已完成！
📄 文件路径：{路径}
请您审核：
- 编排步骤是否合理？
- 目标表属性是否正确？
- 字段设计是否符合预期？
回复"确认"进入步骤3，或指出需要修改的内容。
- 记录模型设计文档路径到状态中
步骤3：SQL编写
用户确认模型设计后才能进入。本步骤由本 skill 主导，调用 write-sql 完成：
3.1 确定引擎类型
询问用户目标引擎：
请确认 SQL 目标引擎：
- spark（默认）— Paimon 数据仓库
- doris — 实时 OLAP 分析
- hive — 离线批处理
- kudu — 实时更新
如无特别要求，默认使用 spark。
3.2 读取文件并组装 context
本 skill 负责以下工作（不是 write-sql 的职责）：
- 读取需求文档：使用 Read 工具读取步骤1产出的 REQ 文件（
./ai_text/REQ-DATA-xxx.md） - 读取模型设计文档：使用 Read 工具读取步骤2产出的 MDDS 文件（
./ai_text/MDDS-DATA-xxx.md） - 组装 context：将两个文档内容拼接为完整的上下文文本
- 确定输出路径：从步骤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 完成后：
- 确认 SQL 文件已写入 output_path
- 简要展示 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）
- 步骤1：
- 简单取数模式：默认仅在对话中展示 SQL，用户要求时写入
./ai_text/QUERY-{时间戳}.sql
完成标志
- 数据开发模式：步骤1/2/3全部完成，用户均已确认，SQL文件已写入
- 简单取数模式：SQL已生成并展示给用户