Create Node Supplement

节点补数据 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 安装指南。

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 检查凭证状态

aliyun configure list

检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。

如果没有有效 profile，请在此停止。

1. 从 Alibaba Cloud Console 获取凭证
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 与插件版本：

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。

6. IMPORTANT: Parameter Confirmation

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

7. 完整命令链

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

# 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
#    普通模式：SupplementId = 上一步返回的 SubmitId
#    海量模式：SubmitId 是 jobId，必须用 get-operation-submit-status 取 ExternalBizId
JOB_ID=<上一步返回的 SubmitId>
aliyun dataphin-public get-operation-submit-status --dataphin-profile <p> --env $ENV \
  --job-id $JOB_ID --user-agent "$USER_AGENT" --format json \
  | jq '.OperationSubmitJob | {JobId, OperationStatus, Progress, ExternalBizId}'
# ExternalBizId 形如 f_<rootNodeId>_<date>_<random>，这才是真正的 SupplementId/FlowId

# 5) 跟踪工作流（按业务日期分 dagrun）
SUPPLEMENT_ID=<ExternalBizId>
aliyun dataphin-public get-supplement-dagrun --dataphin-profile <p> --env $ENV \
  --supplement-id $SUPPLEMENT_ID --user-agent "$USER_AGENT" --format json \
  | jq '.DagrunList[] | {Id,BizDate,Status,Duration}'
# Status: INIT / WAITING / RUNNING / SUCCESS / FAILED

# 6) 查 dagrun 下所有节点实例
DAGRUN_ID=<上一步返回的 Id>
aliyun dataphin-public get-supplement-dagrun-instance --dataphin-profile <p> --env $ENV \
  --dagrun-id $DAGRUN_ID --user-agent "$USER_AGENT" --format json \
  | jq '.InstanceList[] | {NodeName:.NodeInfo.Name,Index,DueTime,Status:.StatusList,Duration}'

8. Observability

本 Skill 属于 alibabacloud-dataphin-skills 套件，继承父 Skill alibabacloud-dataphin-skills 的 session-id，子 Skill 不再重新生成。

所有调用 Alibaba Cloud API 的 aliyun 命令必须携带：

--user-agent AlibabaCloud-Agent-Skills/create-node-supplement/{session-id}

其中 {session-id} 替换为父 Skill 生成的 32 位小写十六进制字符串。

9. 参数要点

10. 常见报错

11. ✗ 不要做

• ✗ 用调度日填 bizdate：bizdate 默认 T-1，调度日填业务日期会导致补数据范围错位
• ✗ 直接复制 IDE 页面 URL 中的 nodeId：URL 上有时是 bizNodeId（pipeline 草稿 ID）而非节点 ID
• ✗ 多个项目跨补：同一次 create-node-supplement 仅支持当前 profile 项目，不支持跨项目
• ✗ 用 --start-biz-date today 形式：必须 yyyymmdd 数字字符串
• ✗ list-nodes 不传 --node-sub-biz-type-list：该参数必填，否则直接报错
• ✗ --node-id-list 传 JSON 数组：CLI 把每个参数当做一个 JSON 对象解析，数组会被当成第一个元素解析而报错
• ✗ 海量模式下把 SubmitId 当 SupplementId 用：必须经 get-operation-submit-status 取 ExternalBizId
• ✗ 裸写 --contain-all-down-stream：该参数是 bool 类型，必须带 true / false

12. 验证与诊断

循环检查各业务日期的 dagrun 与实例状态：

# 总览
aliyun dataphin-public get-supplement-dagrun --dataphin-profile <p> --env $ENV \
  --supplement-id $SUPPLEMENT_ID --user-agent "$USER_AGENT" --format json \
  | jq '.DagrunList[] | {BizDate,Status,Duration}'

# 单个 dagrun 实例明细
aliyun dataphin-public get-supplement-dagrun-instance --dataphin-profile <p> --env $ENV \
  --dagrun-id $DAGRUN_ID --user-agent "$USER_AGENT" --format json \
  | jq '.InstanceList[] | {NodeName:.NodeInfo.Name,Status:.StatusList,Duration}'

13. 相关命令

• aliyun dataphin-public list-nodes — 查节点 ID（必须传 --node-biz-type / --node-sub-biz-type-list / --schedule-type）
• aliyun dataphin-public create-node-supplement — 发起补数据
• aliyun dataphin-public get-operation-submit-status — 海量模式下由 jobId（SubmitId）取真正 SupplementId（ExternalBizId）
• aliyun dataphin-public get-supplement-dagrun — 工作流总览（需真正 SupplementId）
• aliyun dataphin-public get-supplement-dagrun-instance — 实例级状态
• aliyun dataphin-public list-node-down-stream — 创建前查询下游做参考
• find-tenant-root-node.md — 节点 ID / DagId 等知识
• grant-data-source-permission.md — 若节点需 PROD 但 HasProd=false，先按此 skill 处理发布