Add one-skill

2026-05-13 11:03:00 +08:00
parent a4c8b29176
commit f9e36ef92d
34 changed files with 7656 additions and 0 deletions
--- a/one-skill/smart-data-developer/SKILL.md
+++ b/one-skill/smart-data-developer/SKILL.md
@@ -0,0 +1,413 @@
+---
+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 优先 + 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已生成并展示给用户
+
+---