dc-dataquery-cn · 星云平台自助查询（国内）

通过 SQL 查询星云平台国内数仓，并直接向用户返回查询结果。

使用场景

当用户有下面这类需求时使用本 skill：

帮忙查数仓数据
跑一段 SQL
查询 StarRocks / Kyuubi / Spark 数仓
查看雷鸟数仓、鸿鹄 AI 语音数仓、鸿鹄 IoT 数仓中的数据

如果用户没有明确说 skill 名称，也应主动用这套流程识别数据源、补齐参数并执行查询。

数仓映射

数仓	datasourceId	常用 queryEngine
雷鸟数仓	`686bbe98ac50393b137f3dc2`	`StarRocks`, `Kyuubi`
鸿鹄 AI 语音数仓	`686b871fac50393b137f3db7`	`Spark`
鸿鹄 IoT 数仓	`686b86cfac50393b137f3db6`	`Spark`

前置条件

执行查询前，至少需要：

明确的数据源（或可映射到某个数仓）
明确的查询引擎
明确的 SQL

运行时依赖环境变量 TCL_SKILL_USER_KEY，由 SkillHub 在安装时将占位符 TCL_SKILL_USER_KEY密钥，可以通过以下方式获取：1.Windows 读取 %USERPROFILE%\.env\skill-hub-user-key 文件或执行 scripts/tcl-skills-hub-api-key.cmd 脚本获取密钥； 2.Linux/macOS 读取 ~/.env/skill-hub-user-key 文件或执行 scripts/tcl-skills-hub-api-key.sh 脚本获取密钥。如果用户没配置密钥，请提示他到https://platform-eaglelab.tcl.com/skill-page/manage/keys复制命令配置密钥 替换为真实值。若脚本报告 key 无效，说明注入尚未完成。

使用方法

先识别用户要查的数仓、引擎和 SQL。
如果信息不完整，先追问缺失项。
如果用户只有自然语言需求，可以帮助整理 SQL 草案，但必须先让用户确认。
信息齐全后执行：

python3 <skill_dir>/scripts/execute_query.py \
  --sql "<SQL>" \
  --engine <引擎> \
  --datasource <数据源 ID> \
  --api-key TCL_SKILL_USER_KEY密钥，可以通过以下方式获取：1.Windows 读取 %USERPROFILE%\.env\skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.cmd 脚本获取密钥； 2.Linux/macOS 读取 ~/.env/skill-hub-user-key 文件 或 执行 scripts/tcl-skills-hub-api-key.sh 脚本获取密钥。如果用户没配置密钥，请提示他到https://platform-eaglelab.tcl.com/skill-page/manage/keys复制命令配置密钥

根据脚本返回结果向用户回复：
- 有数据：回复 ✅ 查询成功，共 N 行，并展示最多 10 行表格
- 超过 10 行：只展示前 10 行，并补一句 仅展示前 10 行。
- 无数据：回复 ✅ 查询成功，但无数据返回（0 行）
- 失败：回复 ❌ 查询失败: <错误信息>

脚本输出只有两种：

成功：ok / rows / headers / data
失败：ok / error

注意事项

优先补齐查询信息，不要猜测用户意图
不擅自修改 SQL，除非用户明确要求并确认
不暴露鉴权信息、请求头或环境变量内容
只返回真实且对用户有帮助的查询结果
表格展示时：null 显示为空字符串；换行替换为空格；| 替换为全角 ｜；超过 120 个字符时截断并加 ...；对象或数组直接使用脚本输出的 JSON 字符串

故障排查

脚本失败时统一返回 {"ok": false, "error": "<原始错误信息>"}，skill 根据内容向用户如实反馈，不做额外包装。常见场景：

Key 无效：脚本报告 TCL_SKILL_USER_KEY not set or invalid，提示用户确认 SkillHub 注入是否完成
HTTP 错误：脚本返回 HTTP {code}: {body}，如实告知状态码和接口返回内容
网络错误：脚本返回底层错误原因，如实反馈
业务错误：脚本返回接口 msg / message / error 字段原文，如实反馈
查询结果为空：ok: true 且 rows: 0，按成功但无数据处理

文件结构

dc-dataquery-cn/
├── SKILL.md              # skill 说明与使用规范
└── scripts/
    └── execute_query.py  # 实际查询执行脚本