# ODPS Skills — 自包含数据分析工具包

独立的 Python 包，包含 3 个 CLI 工具（skill），用于 ODPS/MaxCompute 数据分析。

## 安装 & 配置

### 1. 安装包

```bash
cd skills
uv pip install -e .
```

### 2. 配置产出路径（必选）

所有 skill 的产出文件（production_code/、output/ 等）都基于一个固定的基础路径。
安装后必须配置，配置一次即可：

```bash
export ODPS_SKILLS_DATA_DIR=/your/project/root
```

写入 shell 配置文件（如 `~/.zshrc`、`~/.bashrc`、`.env` 等）可永久生效。

> 后续维护：如果项目目录迁移，只需改这一个环境变量。

### 3. 验证

```bash
run-sql --help
fetch-daily --help
fetch-table-code --help
```

## Skills 一览

| Skill | CLI 命令 | 用途 |
|-------|----------|------|
| `odps-run-query` | `run-sql` | 执行 SQL 查询，输出 CSV |
| `odps-fetch-daily` | `fetch-daily` | 按天增量获取数据（并发） |
| `odps-fetch-table-code` | `fetch-table-code` | 获取表的生产代码和 schema |

## 产出目录

所有产出基于 `$ODPS_SKILLS_DATA_DIR`（下文简称 `$ROOT`）：

```
$ROOT/
├── tasks/某个分析/
│   ├── query.sql
│   └── output/
│       ├── query_20260301_20260305.csv    ← run-sql
│       └── query/                          ← fetch-daily
│           ├── 20260301.csv
│           └── 20260302.csv
│
└── production_code/                        ← fetch-table-code
    ├── loghubods.my_table.sql              ← 生产 ETL 代码
    └── loghubods.my_table.json             ← schema（列名、类型、上游依赖）
```

| 目录 | 来源 | 说明 |
|------|------|------|
| `{sql_dir}/output/` | run-sql / fetch-daily | 跟随 SQL 文件位置 |
| `$ROOT/production_code/` | fetch-table-code | 表的代码 `.sql` + 结构 `.json` 统一存放 |

## 路径配置方式

| 优先级 | 方式 | 适用场景 |
|--------|------|----------|
| 1 | `--output-dir /path` | 临时覆盖（仅 fetch-table-code 支持） |
| 2 | `ODPS_SKILLS_DATA_DIR=/path` | **推荐**，配置一次永久生效 |

未配置环境变量且未传 `--output-dir` 时，CLI 会报错并提示配置方法。

## 包结构

```
skills/
├── pyproject.toml
├── README.md
├── src/odps_skills/
│   ├── __init__.py
│   ├── config.py              # 路径配置（ODPS_SKILLS_DATA_DIR）
│   ├── client.py              # ODPSClient
│   ├── dataworks.py           # DataWorksClient
│   ├── feishu.py              # 飞书 API
│   ├── run_sql.py             # run-sql CLI
│   ├── fetch_daily.py         # fetch-daily CLI
│   └── fetch_table_code.py    # fetch-table-code CLI
├── odps-run-query/SKILL.md
├── odps-fetch-daily/SKILL.md
└── odps-fetch-table-code/SKILL.md
```