武阳
128 lines
4.4 KiB
Markdown
128 lines
4.4 KiB
Markdown
# data-factory-sql
|
||
|
||
通过 [Kyuubi HTTP API](https://mi.feishu.cn/wiki/Svthwh7g9isyKbkIXO0czfX5nef) 在小米数据工场（[data.mioffice.cn](https://data.mioffice.cn/workspace)）执行 SQL 的 Claude Code / OpenCode skill。
|
||
|
||
**特点**：
|
||
|
||
- ✅ 纯 HTTP API，**无需浏览器/Chrome 扩展**
|
||
- ✅ 支持 `auto` / `presto` / `spark` / `doris` / `hologres` 多引擎
|
||
- ✅ 自动轮询 + URL 编码 + nextQueryId 跟踪 + 错误恢复
|
||
- ✅ 结果落 CSV，stdout 输出结构化 JSON 摘要供 agent 解析
|
||
- ✅ 跨平台（Windows / Mac / Linux），仅依赖 Python 3.8+ 与 `requests`
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
### 1. clone 到 skill 目录
|
||
|
||
```bash
|
||
# Claude Code
|
||
git clone git@git.n.xiaomi.com:zhongsiyao/data-dactory-fetch-skill.git \
|
||
~/.claude/skills/data-factory-sql
|
||
|
||
# OpenCode 同理（路径替换为 ~/.config/opencode/skills/data-factory-sql 或对应位置）
|
||
```
|
||
|
||
> 关键：clone 时**目标目录名必须是 `data-factory-sql`**（与 SKILL.md frontmatter 里的 `name` 字段一致）。
|
||
|
||
### 2. 申请 Token
|
||
|
||
打开数据工场 → 空间配置 → Verification Token 列表 → **生成新的 Token**：
|
||
|
||
> https://data.mioffice.cn/workspace/?wid=<YOUR_WORKSPACE_ID>#/workspace/<YOUR_WORKSPACE_ID>/config?tab=tokenList
|
||
|
||
把上面 URL 里的 `<YOUR_WORKSPACE_ID>` 替换成你自己的 workspace id（在数据工场页面顶部可见）。
|
||
|
||
⚠️ **Token 与服务地址必须同集群**。本 skill 默认 `cnbj1`（中国北京），所以 token 必须也是 cnbj1 下生成的，否则会报"找不到元信息"。其他集群用 `--cluster cnbj2 / alsgp0 / ...`。
|
||
|
||
### 3. 配置 Token
|
||
|
||
按以下任一方式（优先级从高到低）：
|
||
|
||
```bash
|
||
# 方式 A：环境变量
|
||
export KYUUBI_TOKEN=<your_token>
|
||
|
||
# 方式 B：默认文件路径（Windows）
|
||
echo <your_token> > "C:\workspace\data-factory-token.txt"
|
||
|
||
# 方式 C：默认文件路径（Mac / Linux）
|
||
mkdir -p ~/.config/data-factory && echo <your_token> > ~/.config/data-factory/token
|
||
|
||
# 方式 D：每次调用时 --token 参数（不推荐，会出现在命令行历史）
|
||
```
|
||
|
||
### 4. 验证
|
||
|
||
```bash
|
||
python ~/.claude/skills/data-factory-sql/run_sql.py --print-config
|
||
python ~/.claude/skills/data-factory-sql/run_sql.py "SELECT 1 AS id, 'hello' AS msg"
|
||
```
|
||
|
||
成功输出：stderr 表格预览 + stdout 一行 JSON 摘要（含 queryId / engine / rows / cols / output 路径）。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 跑现成的 SQL
|
||
|
||
```bash
|
||
python ~/.claude/skills/data-factory-sql/run_sql.py "SELECT 1"
|
||
```
|
||
|
||
### 多行 SQL 用文件
|
||
|
||
```bash
|
||
python ~/.claude/skills/data-factory-sql/run_sql.py -f my_query.sql --engine spark
|
||
```
|
||
|
||
### 在 Claude Code / OpenCode 里调用
|
||
|
||
skill 已注册触发词：「跑个 SQL」「数据工场查一下」「跑一下这条 SQL」等。直接说自然语言或贴 SQL 即可，agent 会自动调用。
|
||
|
||
---
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
data-factory-sql/
|
||
├── SKILL.md # Agent 触发文档（含红线 / 工作流 / 错误码）
|
||
├── kyuubi_client.py # Kyuubi HTTP API client（提交 → 轮询 → 拉结果 → 关闭）
|
||
├── run_sql.py # CLI 入口
|
||
└── README.md # 本文件
|
||
```
|
||
|
||
详细的 agent 行为规范、错误码、状态机说明见 [SKILL.md](./SKILL.md)。
|
||
|
||
---
|
||
|
||
## 与业务知识的边界
|
||
|
||
本仓库**只做通用 SQL 执行能力**（"工具"层），不包含：
|
||
|
||
- 业务表的字段含义 / 枚举值 / 取值约束
|
||
- 常用 JOIN / 过滤模板
|
||
- 业务指标的归因 SQL
|
||
|
||
这些"领域知识"会维护在独立仓库（**TODO：链接占位**）作为知识库，由本 skill 的"模式 B"消费。这种分离让工具能复用、知识库能独立演进，符合 AI Native 落地的工具/知识两层架构。
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
| 现象 | 排查方向 |
|
||
|------|----------|
|
||
| `auth: HTTP 401` | token 失效 / 过期 / 错位（cnbj2 token 用在 cnbj1）|
|
||
| `query: errCode 4007499 ... do not have permission ...` | 用户没有该 catalog/table 的权限。**注意 `hive_*` 与 `iceberg_*` catalog 的权限可能不同**——优先尝试用户原 SQL 的 catalog |
|
||
| `query: errCode 4007402` | 工场认证异常，重新生成 token |
|
||
| `query: errCode 4007415` | queryId 编码错误。本 client 内部已修复（`requests` 的 `params` 自动编码，不要预编码） |
|
||
| 状态永远不到 FINISHED | 用户旧 demo 用的状态值是 `QUEUED/FAILED/CANCELLED`，**实际是 `PENDING/RUNNING/FINISHED/ERROR/TIMEOUT/CLOSED`** |
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
内部使用。仅限小米员工。
|