/create-node-supplement

name: create-node-supplement
description: |
  对 Dataphin 调度节点发起补数据（按业务日期回填历史数据）。触发场景：补数据 / 补跑 / 回填数据 / backfill / supplement / create-node-supplement / dagrun 状态跟踪。流程：list-nodes（必须传 --node-sub-biz-type-list）→ create-node-supplement → 海量模式经 get-operation-submit-status 取 ExternalBizId → get-supplement-dagrun → get-supplement-dagrun-instance。关键点：bizdate 默认 T-1；--env 必须匹配 HasDev/HasProd；--node-id-list 传单个 JSON 对象字符串 {"Id":"n_xxx"}；create-node-supplement 返回的 SubmitId 是 jobId，真正 SupplementId 是 ExternalBizId；小时任务用 --min-due-time/--max-due-time。触发词：补数据、补跑、回填数据、重跑任务、backfill、supplement、create-node-supplement、dagrun。

节点补数据 Skill

1. Scenario Description

场景：需要按业务日期对调度节点及其下游进行历史数据回填，或修正某段时间内的产出数据。

本 Skill 覆盖从节点定位、补数据提交、到 dagrun 与实例级跟踪的完整流程，并区分普通模式与海量模式（含所有下游）。

Background Knowledge

• **业务日期 bizdate** = 任务的"业务归属日"。Dataphin 默认 `bizdate = T-1`（昨天），即调度日 `cyctime` 凌晨产出 T-1 的数据。补数据的 `--start-biz-date` / `--end-biz-date` 是**业务日期**，不是调度日。
• **节点 ID 仅对应一个环境**：`n_xxx` 是 DEV 节点 ID 还是 PROD 节点 ID 取决于发布是否成功。`HasDev=true` 意味着 DEV 侧有节点；`HasProd=true` 意味着 PROD 侧也有节点。**未发布到 PROD 的项目用 `--env DEV`**，否则 `DPN.OP.NodeNotFound`。
• **小时调度** 一个补数据日会按 cron 展开成 N 个实例（如 `0 45 8,20 * * ?` 展开为 08:45 与 20:45 两个 due-time 实例）。`--min-due-time` / `--max-due-time` 可在小时任务中限定补哪几个时点。
• **依赖关系自动遵守**：多个根节点同 batch 提交时，按 DAG 依赖顺序执行。下游节点会等上游完成。

Architecture

用户请求 → 确认参数 → list-nodes 定位节点
  → create-node-supplement（普通 / 海量模式）
  → 海量模式：get-operation-submit-status 取 ExternalBizId
  → get-supplement-dagrun 跟踪各业务日期
  → get-supplement-dagrun-instance 查看节点实例状态

涉及 Dataphin OpenAPI

• `ListNodes` — 查询节点元数据（必须传 NodeBizType / NodeSubBizTypeList / ScheduleType）
• `CreateNodeSupplement` — 发起补数据
• `GetOperationSubmitStatus` — 海量模式下由 jobId 取真正 SupplementId
• `GetSupplementDagrun` — 查询补数据 dagrun 列表
• `GetSupplementDagrunInstance` — 查询 dagrun 下节点实例
• `ListNodeDownStream` — 创建前查询下游做参考

2. Installation

# 安装 aliyun CLI（>= 3.4.8）
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

# 安装 dataphin-public 插件
aliyun plugin install --names aliyun-cli-dataphin-public

# 验证
aliyun dataphin-public --help

详见 [CLI 安装指南](./references/cli-installation-guide.md)。

3. Environment Variables

> 凭证与环境变量由父 skill `alibabacloud-dataphin-skills` 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

4. Authentication

Pre-check: Credentials Required

> **Security Rules:** > - **NEVER** 读取、回显或打印凭证环境变量（禁止对 AccessKey ID / Secret 做任何输出或日志） > - **NEVER** 要求用户在本会话或命令行直接输入 AK/SK > - **NEVER** 使用 `aliyun configure set` 写入字面量凭证 > - **ONLY** 使用 `aliyun configure list` 检查凭证状态 > > ```bash > aliyun configure list > ``` > 检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。 > > **如果没有有效 profile，请在此停止。** > 1. 从 [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak) 获取凭证 > 2. 在会话外配置（终端执行 `aliyun configure`，或在 shell profile 中设置环境变量） > 3. 重新运行 `aliyun configure list` 确认有效后再继续

Pre-check: Aliyun CLI plugin update required

> [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation. > [MUST] run `aliyun plugin update` to ensure that any existing plugins are always up-to-date. > > 执行前确认 CLI 与插件版本： > ```bash > aliyun version > aliyun plugin list > ```

5. RAM Policy

> **[MUST] Permission Failure Handling:** When any command or API call fails due to permission errors at any point during execution, follow this process: > 1. Read `../../ram-policies.md` to get the full list of permissions required by this SKILL > 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions > 3. Pause and wait until the user confirms that the required permissions have been granted

本 skill 最小权限见 [../../ram-policies.md](../../ram-policies.md)。

6. IMPORTANT: Parameter Confirmation

执行 `create-node-supplement` 前必须向用户确认以下参数，禁止静默提交：

| 参数 | 说明 | |------|------| | `--env` | DEV 或 PROD（默认 PROD），必须与节点实际发布环境一致 | | `--node-id-list` | 根节点 ID 列表（单个 JSON 对象字符串 / 节点） | | `--start-biz-date` / `--end-biz-date` | 业务日期闭区间，格式 `yyyymmdd` | | `--contain-all-down-stream` | 是否联动所有下游节点（海量模式） | | `--parallelism` | 同一业务日期内实例并发上限 |

7. 完整命令链

TENANT_ID=<tenant-id>
PROJECT_ID=<project-id>
ENV=DEV   # 或 PROD（必须该任务已成功发布到 PROD，HasProd=true）
USER_AGENT="AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}"

# 1) 取真实业务日期（绝对不要依赖会话上下文时间）
TODAY=$(date "+%Y%m%d")
BIZDATE=$(date -v-1d "+%Y%m%d")  # macOS；Linux: date -d "-1 day" "+%Y%m%d"
echo "今天=$TODAY 业务日期(T-1)=$BIZDATE"

# 2) 拿目标节点 ID（list-nodes 必须传 node-biz-type / node-sub-biz-type-list / schedule-type / env）
#    SHELL 任务：--node-biz-type SCRIPT --node-sub-biz-type-list SHELL
#    SQL 任务：--node-biz-type SCRIPT --node-sub-biz-type-list MAX_COMPUTE_SQL / HIVE_SQL 等
#    逻辑表任务：--node-biz-type LOGICAL_TABLE
aliyun dataphin-public list-nodes --dataphin-profile <p> --env $ENV \
  --node-biz-type SCRIPT --node-sub-biz-type-list SHELL --schedule-type NORMAL \
  --search-text "<task-name>" --page 1 --page-size 10 \
  --user-agent "$USER_AGENT" --format json \
  | jq '.PageResult.NodeList[] | {Id,Name,HasProd,HasDev,SubDetailType}'

# 3) 发起补数据（一次可多个根节点，每个节点一个 JSON 对象字符串）
#    注意：--node-id-list 不是 JSON 数组，而是多个 JSON 对象参数
aliyun dataphin-public create-node-supplement --dataphin-profile <p> --env $ENV \
  --node-id-list '{"Id":"n_8005597591266000896"}' '{"Id":"n_8005606971474444288"}' \
  --start-biz-date $BIZDATE --end-biz-date $BIZDATE \
  --node-supplement-name "supp_$(date +%Y%m%d_%H%M%S)" \
  --parallelism 1 --user-agent "$USER_AGENT" --format json
# 返回 SubmitId（普通模式下即为 SupplementId；海量模式下是 jobId，需第 4 步转换）

# 海量模式：联动根节点及其所有下游
aliyun dataphin-public create-node-supplement --dataphin-profile <p> --env $ENV \
  --node-id-list '{"Id":"n_8005597591266000896"}' \
  --start-biz-date $BIZDATE --end-biz-date $BIZDATE \
  --contain-all-down-stream true \
  --node-supplement-name "supp_$(date +%Y%m%d_%H%M%S)" \
  --parallelism 1 --user-agent "$USER_AGENT" --format json

# 4) 取真正的 SupplementId
#    普通