data_analysis/skills/README.md

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

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

安装 & 配置

1. 安装包

cd skills
uv pip install -e .

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

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

export ODPS_SKILLS_DATA_DIR=/your/project/root

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

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

3. 验证

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