/pause-task-instance

name: pause-task-instance
description: |
  暂停/恢复 Dataphin 调度任务实例（按任务名 + 业务日期 + 运行时点定位并触发 PAUSE/RESUME）。触发场景：实例暂停 / 暂停调度 / 恢复调度 / pause / resume / operate-instance PAUSE / 阻止实例被调度拉起 / 小时任务暂停某个时点。完整流程：list-instances（按 bizdate + DueTime 筛选）→ operate-instance(PAUSE/RESUME) → get-physical-instance 验证 SchedulePaused。关键点：bizdate 默认 T-1（今日运行的实例业务日期通常是昨天）；小时任务一个 bizdate 有多个实例，需按 DueTime 选定时点；PAUSE 成功后实例 StatusList 可能仍为 WAIT_SCHEDULE，真正判据是 NodeInfo.SchedulePaused=true。触发词：暂停实例、pause、恢复实例、resume、operate-instance PAUSE、暂停调度、阻止调度。

暂停/恢复任务实例 Skill

1. Scenario Description

场景：周期任务在某个业务日期的实例尚未运行（`WAIT_SCHEDULE`），但需要阻止其在到达调度时间点时被拉起；或已暂停后需要恢复调度。典型用途：

• 小时任务某个时点的实例暂时不想跑（如 20:45 实例先暂停，待数据就绪后再恢复）
• 实例等待调度时临时挂起，避免占用资源或误触发

本 Skill 按「任务名 + 业务日期 + 运行时点（DueTime）」定位实例，执行 `OperateInstance --operation PAUSE`（暂停）或 `RESUME`（恢复），并给出验证方法。

Architecture

用户请求 → 确认参数 → list-instances 按 bizdate 查询
  → 按 DueTime 筛选目标时点实例 → operate-instance PAUSE/RESUME
  → get-physical-instance 验证 SchedulePaused → 输出结论

涉及 Dataphin OpenAPI：

• `ListProjects` — 枚举项目（同名任务可能跨项目）
• `ListInstances` — 按任务名 + 业务日期查实例，输出 `DueTime`（毫秒时间戳）
• `OperateInstance` — 触发 PAUSE / RESUME
• `GetPhysicalInstance` — 验证 `NodeInfo.SchedulePaused`

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 >= 3.4.8 required

> 运行 `aliyun version` 确认版本 >= 3.4.8。若未安装或版本过低，从 https://aliyuncli.alicdn.com 安装/升级（见 `references/cli-installation-guide.md`）。

Pre-check: Aliyun CLI plugin update required

> [MUST] 运行 `aliyun configure set --auto-plugin-install true` 开启自动插件安装。 > [MUST] 运行 `aliyun plugin update` 确保插件为最新版本。

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 涉及的最小权限：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dataphin:ListProjects",
        "dataphin:ListInstances",
        "dataphin:OperateInstance",
        "dataphin:GetPhysicalInstance"
      ],
      "Resource": "*"
    }
  ]
}

详见 [RAM 策略参考](../../ram-policies.md)。

6. Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call, > ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, > passwords, domain names, resource specifications, etc.) MUST be confirmed with the > user. Do NOT assume or use default values without explicit user approval.

执行前必须向用户确认以下参数：

| 参数 | 必填 | 说明 | 示例 | |------|------|------|------| | `--op-tenant-id` / `--tenant-id` | 条件 | 租户 ID；profile 已配置时可省略 | `300115489` | | `--dataphin-profile` / `--profile` | 条件 | 本地 profile 名；省略则使用 current profile | `env23` | | `--env` | 推荐 | `DEV` / `PROD`（默认 `PROD`） | `PROD` | | `TASK_NAME` | 必 | 要暂停/恢复的任务名称 | `cli_test` | | `BIZ_DATE` | 推荐 | 业务日期 `yyyymmdd`；省略则取 T-1 | `20260629` | | `DUE_TIME` | 可选 | 目标运行时点 `HH:MM`；小时任务多实例时用于筛选 | `20:45` | | `OPERATION` | 必 | `PAUSE` 或 `RESUME` | `PAUSE` | | `PROJECT_ID` | 可选 | 若已知项目 ID，可直接指定，跳过跨项目遍历 | `7295715579274176` |

7. Observability

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

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

--user-agent AlibabaCloud-Agent-Skills/pause-task-instance/{session-id}

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

8. Core Workflow

8.1 计算业务日期

# 优先使用真实系统日期，不要依赖会话上下文时间
TODAY=$(date "+%Y%m%d")
# macOS
BIZDATE=$(date -v-1d "+%Y%m%d")
# Linux 用：BIZDATE=$(date -d "-1 day" "+%Y%m%d")
echo "today=$TODAY bizdate=$BIZDATE"

> **关键**：Dataphin 默认 `bizdate = T-1`。用户说「当日 20:45 运行的实例」时，该实例的业务日期通常是**昨天**（T-1），而不是今天。若用今日作为 bizdate 查不到实例，请回退到 T-1。

8.2 定位目标实例

已知项目 ID

ENV=PROD
PROJECT_ID="<project-id>"
TASK_NAME="<task-name>"
BIZDATE="<biz-date>"

aliyun dataphin-public list-instances \
  --env "$ENV" \
  --project-id "$PROJECT_ID" \
  --schedule-type NORMAL \
  --search-text "$TASK_NAME" \
  --min-biz-date "$BIZDATE" \
  --max-biz-date "$BIZDATE" \
  --page 1 --page-size 50 \
  --format json \
  --user-agent AlibabaCloud-Agent-Skills/pause-task-instance/{session-id} \
  | jq -r '.PageResult.Data[]? | "\(.Id)\t\(.NodeInfo.Name)\t\(.DueTime)\t\(.StatusList|join(","))"'

按运行时点筛选（小时任务）

`DueTime` 是毫秒时间戳。将其转为 `HH:MM` 后筛选目标时点：

TARGET_HHMM="20:45"

aliyun dataphin-public list-instances \
  --env "$ENV" \
  --project-id "$PROJECT_ID" \
  --schedule-type NORMAL \
  --search-text "$TASK_NAME" \
  --min-biz-date "$BIZDATE" \
  --max-biz-date "$BIZDATE" \
  --page 1 --page-size 50 \
  --format json \
  --user-agent AlibabaCloud-Agent-Skills/pause-task-instance/{session-id} \
  | jq -r '.PageResult.Data[]? | "\(.Id)\t\(.DueTime)