# Data Query Skills

面向团队私有仓库分发的 4 个 ODPS 数据查询 Skill 和 1 个飞书发布 Skill：

- `odps-ad-risk-analysis`
- `odps-growth-fission-report`
- `odps-product-efficiency-report`
- `query-user-behavior-path`
- `feishu-data-publisher`

每个 Skill 都可以独立安装，运行时只读取当前使用者自己的环境变量，不依赖作者机器上的项目目录或凭证文件。

## 环境准备

```bash
python3 -m pip install -r requirements.txt
```

在仓库外配置以下环境变量：

```bash
export ODPS_ACCESS_ID='个人 Access ID'
export ODPS_ACCESS_SECRET='个人 Access Secret'
export ODPS_PROJECT='ODPS 项目名'
export ODPS_ENDPOINT='ODPS Endpoint'
```

需要把查询结果发布为飞书在线表格时，再配置：

```bash
export FEISHU_APP_ID='飞书自建应用 App ID'
export FEISHU_APP_SECRET='飞书自建应用 App Secret'
export FEISHU_TARGET_CHAT_ID='目标群 chat_id'
```

飞书配置不是执行 ODPS 查询的前置条件。发布 Skill 支持 CSV、XLS 和 XLSX，上传后将链接权限设置为“互联网获得链接的任何人可编辑”，再把在线表格卡片发送到目标群。该权限较宽，发布前应确认结果中不含不应公开的数据。

可以复制 `.env.example` 到个人私有配置目录，例如 `~/.config/data-query-skills/odps.env`，填写后执行：

```bash
chmod 600 ~/.config/data-query-skills/odps.env
source ~/.config/data-query-skills/odps.env
```

不要把填有真实值的配置文件复制回仓库。每位同事应使用自己的账号和最小权限凭证。

## 从私有 GitHub 仓库安装

```bash
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo <组织>/<仓库> \
  --path \
    skills/odps-ad-risk-analysis \
    skills/odps-growth-fission-report \
    skills/odps-product-efficiency-report \
    skills/query-user-behavior-path \
    skills/feishu-data-publisher
```

私有仓库需要本机已有 Git 凭证，或者配置 `GH_TOKEN`。安装完成后，Skill 会在下一轮 Codex 对话中可用。

## 从其他私有 Git 服务安装

```bash
git clone --branch main --single-branch \
  https://git.yishihui.com/liulidong/data_query_skill.git data-query-skills
mkdir -p ~/.codex/skills
cp -R data-query-skills/skills/* ~/.codex/skills/
```

## 更新已安装 Skill

在之前 clone 的目录中拉取并覆盖安装：

```bash
cd data-query-skills
git pull --ff-only
python3 -m pip install -r requirements.txt
mkdir -p ~/.codex/skills
cp -R skills/* ~/.codex/skills/
```

重新开启一轮 Codex 对话后使用新版本。

## 发布查询结果到飞书

可以让 Codex 在查询完成后调用 `feishu-data-publisher`，也可以直接运行：

```bash
python3 ~/.codex/skills/feishu-data-publisher/scripts/publish_table.py \
  /path/to/report.xlsx \
  --chat-name '前端组' \
  --title '产品效率日报'
```

实际上传前可加 `--dry-run` 做本地预检；只读查询机器人可见群聊可使用 `--list-chats --name '群名'`。

## 安全边界

- Skill 和 Git 仓库不得包含 Access ID、Access Secret、临时 Token 或带 Token 的 LogView URL。
- `scripts/odps_module.py` 只打印 ODPS Instance ID，不打印 LogView URL。
- 查询生成的 CSV、Excel、日志和个人 `.env` 默认不提交。
- 飞书 App Secret、tenant access token 和临时上传 token 不得写入日志或提交。
- 表名、指标口径和风控规则仍属于内部资料，只应放在授权的私有仓库。