zk-data-agent/skills/data-factory-sql/SKILL.md

name, description, when_to_use, aliases, allowed_tools

name	description	when_to_use	aliases	allowed_tools
data-factory-sql	通过小米数据工场 Kyuubi HTTP API 执行 SQL 查询，轮询状态并下载 CSV 结果。适合用户直接给 SQL、要求“跑个 SQL”“数据工场查一下”“查数据”，或基于表结构/字段说明生成 SQL 草稿后执行。	用户希望在小米数据工场执行 SQL、查询 Hive/Presto/Spark/Doris/Hologres 数据、下载查询结果 CSV、或基于数据工场结果做进一步分析时使用。	data-factory, kyuubi-sql, sql-query, 数据工场, 跑SQL	python_exec, python_package, read_file, write_file, ask_user_question

Data Factory SQL Skill

使用这个 skill 作为“小米数据工场 SQL 查询”的统一入口。它通过 Kyuubi HTTP API 提交 SQL、轮询状态、拉取结果并保存 CSV，不依赖浏览器。

本 skill 已安装在项目目录：

skills/data-factory-sql/

关键文件

文件	用途
run_sql.py	CLI 入口，提交 SQL 并输出 JSON 摘要
kyuubi_client.py	Kyuubi HTTP API client
README.md	原始说明和安装/token 配置说明

在本数据 Agent 中使用

不要用 bash 执行 python run_sql.py，也不要用系统 pip 安装依赖。

执行 SQL 必须使用 python_exec：

{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["SELECT 1 AS id, 'hello' AS msg"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}

如果 python_exec 返回缺少 requests，先用 python_package 安装：

{
  "action": "install",
  "packages": ["requests"],
  "timeout_seconds": 120
}

多行 SQL 或复杂 SQL 不要通过命令行字符串硬塞。优先把 SQL 写到当前 session/scratchpad；只有用户明确指定外部目标文件时，才写到用户指定目录，再用 -f 执行：

{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["-f", "<sql_file>", "--engine", "auto"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}

Token 配置

脚本按以下顺序读取 token：

1. --token <value>
2. 环境变量 KYUUBI_TOKEN
3. C:\workspace\data-factory-token.txt
4. ~/.config/data-factory/token

不要把 token 写入项目仓库。推荐让用户在运行环境里配置 KYUUBI_TOKEN，或写到用户 home 下的默认 token 文件。

Token 申请入口：

https://data.mioffice.cn/workspace/?wid=<YOUR_WORKSPACE_ID>#/workspace/<YOUR_WORKSPACE_ID>/config?tab=tokenList

注意：token 与服务地址必须同集群。本 skill 默认 cnbj1，如果用户使用其他集群，需要显式传 --cluster cnbj2、--cluster alsgp0 等。

默认配置

项	默认值
集群	cnbj1
Base URL	http://proxy-service-http-cnbj1-dp.api.xiaomi.net
引擎	auto
输出	当前 session/output/data_factory_<时间戳>.csv；如果没有 session 环境，则退回 ~/Downloads/data_factory_<时间戳>.csv
轮询间隔	2.0s
查询超时	600s

两种工作模式

模式 A：用户直接给 SQL

用户提供完整 SQL 时，可以在做基础风险检查后直接执行。

执行前必须检查：

• 是否明显是查询语句，而不是危险写操作。
• 大表查询是否带 dt、日期、分区或合理 limit。
• 用户是否显式指定了 catalog.schema.table、引擎、集群或输出路径。

如果 SQL 看起来会全表扫、跨天扫很多数据，或存在写入/删除/建表等副作用，不要直接执行，先向用户确认。

模式 B：自然语言需求 + 表结构/知识文档

用户没有给完整 SQL，而是给自然语言需求、表结构、字段说明或业务文档时：

1. 先读取用户提供的文档或表结构。
2. 生成 SQL 草稿。
3. 向用户展示 SQL 草稿并等待确认。
4. 用户确认后再执行。
5. 读取 CSV 结果并分析，必要时迭代 SQL。

不要跳过第 3 步。自然语言生成的 SQL 必须先给用户 review。

标准执行流程

1. 判断是“直接 SQL”还是“自然语言生成 SQL”。
2. 如果需要读取表结构或知识文档，先用 read_file。
3. 检查 SQL 风险：分区、时间范围、limit、副作用、catalog/schema/table 是否被擅自改动。
4. 需要确认时，展示 SQL 并停止等待用户确认。
5. 确认后调用 python_exec 执行 skills/data-factory-sql/run_sql.py。
6. 解析 stdout 最后一行 JSON 摘要。
7. 如果 JSON 有 error，把错误直接告诉用户，不要盲目重试。
8. 如果 rows == 0，提示空结果，不要编造数据。
9. 如果有 output，用 read_file 读取 CSV 或根据行数选择采样分析。
10. 用具体数值回答用户问题，并说明结果文件路径。

常用参数

直接执行 SQL

{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["SELECT 1"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}

从文件读取 SQL

{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["-f", "/path/to/query.sql"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}

指定引擎

{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["-f", "/path/to/query.sql", "--engine", "spark"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}

指定输出路径

输出路径优先写到当前 session/output，或用户明确指定的任务目录。不要写项目根目录、源码目录或其他非 session 临时位置。

{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["-f", "/path/to/query.sql", "--output", "/path/to/output/result.csv"],
  "timeout_seconds": 700,
  "max_output_chars": 20000
}

调试配置

{
  "script_path": "skills/data-factory-sql/run_sql.py",
  "args": ["--print-config"],
  "timeout_seconds": 60,
  "max_output_chars": 12000
}

输出 JSON

成功时 stdout 最后一行是 JSON：

{
  "queryId": "...",
  "engine": "TRINO",
  "rows": 1,
  "cols": 2,
  "elapsed_ms": 5210,
  "columns": [{"name": "id", "type": "BIGINT"}],
  "output": "/path/to/data_factory_20260427_150120.csv"
}

失败时会输出：

{"error": "..."}

退出码：

• 2：输入问题，例如空 SQL。
• 3：认证问题，例如 token 失效。
• 4：SQL 执行错误，例如语法、权限、超时。
• 5：其他 Kyuubi 错误。

红线

禁止：

• 在自然语言生成 SQL 后跳过用户确认直接执行。
• 在 SQL 失败后不读 error 信息盲目重试。
• 大表查询没有 dt、日期范围、分区过滤或合理 limit 就直接执行。
• 擅自修改用户 SQL 里的 catalog/schema/table 名。
• 把 token、CSV 输出或临时 SQL 文件写进项目源码目录。
• 使用 bash 执行 Python 或安装依赖。

必须：

• 使用 python_exec 执行脚本。
• 缺依赖时使用 python_package 安装到当前用户独立 venv。
• 多行 SQL 优先走 -f 文件。
• 解析 stdout 最后一行 JSON 决定下一步。
• 大结果集先汇报行数和文件路径，再决定全量分析或采样。

已知约束

• 状态机是 PENDING / RUNNING / FINISHED / ERROR / TIMEOUT / CLOSED。
• progress 100% 不代表完成，必须等 state == FINISHED。
• nextQueryId 每次轮询都会更新，client 已自动处理。
• 查询 ID 中的 /、;、: 等特殊字符，client 已自动 URL 编码。
• token 与服务地址必须同集群，否则可能报“找不到元信息”。