# dp_dataworks_plugin

**Repository Path**: kangjinhao/dp_dataworks_plugin

## Basic Information

- **Project Name**: dp_dataworks_plugin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 数仓运维 / DataWorks 本地接入

这个目录目前作为 DataWorks 本地工作区使用。

已验证能力：

- 可以通过阿里云 DataWorks OpenAPI 访问 `cn-shanghai`。
- 可以访问项目 `188504`，项目标识为 `noah_ads`。
- 可以枚举该项目下的脚本文件，并读取文件内容。

当前目录的定位：

- 用这里作为后续本地修改、排查、脚本管理入口。
- 复用参考项目 `/Users/ganting/Documents/数仓/atm-sql-file` 里已经存在的 DataWorks API / 同步工具链。
- 不在本目录复制敏感 `.env` 或 AK/SK。
- 优先把重复性运维动作做成脚本，减少浏览器手工点击和 token 消耗。

## 在新电脑上启用（从 GitHub clone 后）

本仓库即分发单元：`dataworks-ops` plugin 与它依赖的 `scripts/`、`.claude/`、`tables/README.md` 一起入库，**以仓库根作为工作目录运行**。新电脑按下面四步即可:

```bash
# 1) 克隆并进入仓库（以仓库根为工作目录，skill 里的 scripts/... 才能解析）
git clone <你的-github-仓库地址> 数仓运维 && cd 数仓运维

# 2) 安装 Python 依赖
python3 -m pip install -r requirements.txt

# 3) 配置凭据（真实文件已被 .gitignore 忽略，不会入库）
cp dataworks-plgin.env.json.example dataworks-plgin.env.json
#   编辑 dataworks-plgin.env.json 填入真实 AK/SK，然后：
source dataworks-plgin.env.json

# 4) 连通性自检
python3 scripts/dataworks_check.py
```

在 Claude Code / Cursor 里启用 plugin：把本仓库根目录作为 workspace 打开，
通过本地 marketplace（`.claude-plugin/marketplace.json`）安装 `dataworks-ops`。
plugin 的确定性脚本用 `${CLAUDE_PLUGIN_ROOT}` 定位，运维脚本用仓库根的 `scripts/`，
两者都要求 workspace = 仓库根。

> 安全提示：`dataworks-plgin.env.json` 含明文 AK/SK，仅本地存在、永不入库；如怀疑泄漏请在阿里云控制台轮换密钥。

## 快速使用

先做连通性检查：

```bash
python3 scripts/dataworks_check.py
```

按关键字列出 DataWorks 文件：

```bash
python3 scripts/dataworks_list_files.py --keyword ads_dataatm --limit 20
```

按 `file_id` 拉取单个文件内容到本地：

```bash
python3 scripts/dataworks_fetch_file.py --file-id 505480202
```

也可以直接指定输出路径：

```bash
python3 scripts/dataworks_fetch_file.py --file-id 505480202 --output ./tmp/pulled_sql/ads_bp_customer_base_to_commission.sql
```

查看某张表当前的数据质量实体、规则、告警订阅和测试结果：

```bash
python3 scripts/dataworks_dqc_inspect.py \
  --table-name ads_upright_customer_monthly_settle_position \
  --match-expression 'pt_yyyymmdd=$[yyyymmdd-1]' \
  --rule-id 30339305 \
  --bizdate 20260521
```

把线上当前数据质量配置反导出成 `dqc_config.json`：

```bash
python3 scripts/dataworks_dqc_export.py \
  --table-name ads_upright_customer_monthly_settle_position \
  --match-expression 'pt_yyyymmdd=$[yyyymmdd-1]' \
  --output tables/ads_upright_customer_monthly_settle_position/dqc_config.exported.json
```

按本地配置预览一张表的数据质量变更：

```bash
python3 scripts/dataworks_dqc_apply.py \
  --config tables/ads_upright_customer_monthly_settle_position/dqc_config.json \
  --run-test \
  --bizdate 20260521
```

确认要写回 DataWorks 时，再加 `--apply`：

```bash
python3 scripts/dataworks_dqc_apply.py \
  --config tables/ads_upright_customer_monthly_settle_position/dqc_config.json \
  --apply
```

只更新 webhook / 告警订阅时，用 `webhook` 子命令：

```bash
python3 scripts/dataworks_dqc_apply.py webhook \
  --config tables/ads_upright_customer_monthly_settle_position/dqc_config.json \
  --apply
```

只更新规则时，用 `rules` 子命令：

```bash
python3 scripts/dataworks_dqc_apply.py rules \
  --config tables/ads_upright_customer_monthly_settle_position/dqc_config.json \
  --apply
```

发布同步先只做 plan，生成线上回滚基线、hash 和 diff：

```bash
python3 scripts/dataworks_deploy_sync.py \
  --phase plan \
  --file-id 505505930 \
  --local-sql tables/ads_upright_customer_monthly_settle_position/etl/ads_upright_customer_monthly_settle_position.sql
```

确认 diff 后才允许写开发态，且必须带 plan 输出的 `remote_sha256`：

```bash
python3 scripts/dataworks_deploy_sync.py \
  --phase update \
  --file-id 505505930 \
  --local-sql tables/ads_upright_customer_monthly_settle_position/etl/ads_upright_customer_monthly_settle_position.sql \
  --message "更新正行存量 ETL" \
  --expected-remote-hash <plan 输出的 remote_sha256> \
  --apply \
  --confirm UPDATE_FILE
```

`update` 后必须先看输出里的 `post_checks`，确认 `same_as_local=true` 且状态为 `PASS`，再提交。提交和发布也必须显式确认，并继续带上本地 SQL 让脚本输出写后快照：

```bash
python3 scripts/dataworks_deploy_sync.py \
  --phase submit \
  --file-id 505505930 \
  --local-sql tables/ads_upright_customer_monthly_settle_position/etl/ads_upright_customer_monthly_settle_position.sql \
  --message "提交正行存量 ETL" \
  --apply \
  --confirm SUBMIT_FILE

python3 scripts/dataworks_deploy_sync.py \
  --phase deploy \
  --file-id 505505930 \
  --local-sql tables/ads_upright_customer_monthly_settle_position/etl/ads_upright_customer_monthly_settle_position.sql \
  --message "发布正行存量 ETL" \
  --apply \
  --confirm DEPLOY_FILE
```

注意：保存态、提交态、生产态要分别反查内容或 hash。最后修改时间一致不代表提交/生产版本已经生效。

补数据预览使用当前 DataWorks MCP / OpenAPI 参数 contract：

```bash
python3 scripts/dataworks_run_cycle_dag.py \
  --node-id 123456789 \
  --bizdate 20260525 \
  --name "ads_xxx_20260525_backfill" \
  --env DEV
```

预览输出里的 `Params` 应包含 `FlowName / NodeId / StartNodeId / IsParallel / IncludeFutureInstance`。如果刚改过 SQL，必须先确认保存态、提交态、生产态都已反查一致，再下发补数据。

## 配置约定

默认复用参考项目：

- `DATAWORKS_REFERENCE_ROOT=/Users/ganting/Documents/数仓/atm-sql-file`
- `DATAWORKS_PROJECT_ID=188504`

如需切换，可在命令前覆盖环境变量：

```bash
DATAWORKS_PROJECT_ID=123456 python3 scripts/dataworks_check.py
```

## 当前边界

- 已验证的是 DataWorks API 连通、项目识别、文件列表读取、单文件内容读取。
- 数据质量这块已验证可通过旧版 `2020-05-18` 质量 API 做实体/规则/测试结果查询与配置。
- 官方 `2024-05-18` Data Quality API 语义更新，但当前 AK 缺少 `dataworks:ListDataQualityScans` 等 RAM 权限，脚本目前默认走旧版可用链路。
- 为避免每次命令都打印 2024 权限 403，`inspect/apply/export` 默认不做 2024 探测；需要时显式加 `--include-modern-probe`。
- 当前目录还不是 Git 仓库；如果你后面要把这里当正式代码仓库管理，需要单独初始化 Git 或换成真实远端仓库。
- 参考项目里的 `dataworks_sync/sync_dataworks.py` 这次实测中 `--dry-run` 仍然进入了本地下载流程，所以现阶段不建议直接把它当“纯预览”命令使用，先用本目录的只读脚本更稳。

## 后续建议

如果你确认要在这个目录里完成完整闭环，我下一步可以继续补：

- 关键词检索后自动拉取对应 SQL 到固定目录
- 将 `scripts/dataworks_deploy_sync.py` 在 1~2 个真实发布任务中继续回看,再决定是否放宽 `all` 模式使用边界
- 针对表运维的常用只读/写操作封装