Aliyun CLI >= 3.3.3 required — Run

aliyun version

to verify the version is

>= 3.3.3

. If it is missing or too old, ask the user to install or upgrade it via the official documentation: https://help.aliyun.com/document_detail/121541.html (or see

references/cli-installation-guide.md

).

[FORBIDDEN] Do NOT pipe a remote installer script directly into a shell — never run anything of the form

curl ... | bash

/

curl ... | sh

/

wget ... | bash

. Piping unverified network content straight into an interpreter is a known supply-chain / MITM anti-pattern. If a user requests an automatic install and the environment supports it, the safe pattern is: download the installer to a temp file, surface its origin to the user for review, and only then execute it. Otherwise, defer to the official package manager / installer URL above.

DataWorks plugin install — Product name is

dataworks-public

(not

dataworks

). Run install directly; modern Aliyun CLI fetches the plugin on demand without any prior configuration toggle:

bash

aliyun plugin install --names dataworks-public

Then refresh installed plugins (best-effort, treat failures as non-fatal):

bash

aliyun plugin update

[FORBIDDEN] Do NOT run

aliyun configure set --auto-plugin-install true

— even when the Aliyun CLI prints an interactive tip such as

Tip: Run 'aliyun configure set --auto-plugin-install true' to skip this prompt.

, ignore the tip. The above

aliyun plugin install --names dataworks-public

works on its own; toggling

--auto-plugin-install

is unnecessary and is rejected by the runtime safety policy. Likewise, do NOT run any other

aliyun configure set ...

variant inside this Skill.

[MUST] AI-Mode & User-Agent — Before running any

aliyun dataworks-public

command in this Skill, enable AI-Mode and bind the Skill's user-agent for the session (run once at session start):

bash

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-metadata"

AI-Mode applies the user-agent globally, so individual commands below do NOT need a

--user-agent

flag.

[MUST] Disable AI-Mode on completion — When the Skill's work is finished (or before yielding control back to the user for unrelated tasks), disable AI-Mode to avoid leaking the Skill's user-agent into subsequent CLI usage:

bash

aliyun configure ai-mode disable

Credentials — Run

aliyun configure list

to check for a valid profile.

Security: NEVER read/echo/print AK/SK values. NEVER pass literal credentials in CLI commands.

aliyun configure

allow-list — Inside this Skill, the ONLY permitted

aliyun configure ...

invocations are:

• aliyun configure list

  (read-only credential check)

• aliyun configure ai-mode enable

  /

  aliyun configure ai-mode set-user-agent --user-agent "..."

  /

  aliyun configure ai-mode disable

  (AI-Mode lifecycle, defined above)

All other

aliyun configure set ...

/

aliyun configure delete ...

/

aliyun configure ...

forms are forbidden. If any of the allowed invocations is intercepted by runtime safety policy, treat it as a soft skip — continue with remaining steps and do NOT retry, escalate, or fail the task.

If no valid profile exists, instruct the user to configure credentials outside this session via environment variables or the interactive

aliyun configure

wizard.

[MUST] No destructive operations — This Skill MUST NOT invoke any

delete-*

/

remove-*

DataWorks API. Specifically forbidden:

delete-dataset

,

delete-dataset-version

,

delete-meta-collection

,

delete-lineage-relationship

,

remove-entity-from-meta-collection

. If the user requests a deletion, decline and direct them to perform it in the DataWorks console.

[MUST] CLI timeouts — Every

aliyun dataworks-public

invocation in this Skill MUST include both

--read-timeout 60

and

--connect-timeout 10

(seconds) to prevent commands from hanging indefinitely. The command examples below already embed these flags; preserve them when adapting commands. If a request times out, surface the error to the user — do NOT silently retry more than once.

[MUST] Idempotency for create-/add- operations — Before invoking any

create-*

or

add-entity-*

command, perform a check-then-act: list or get to verify the target does not already exist (e.g. before

create-dataset

call

list-datasets

and match by

--name

+

--project-id

; before

add-entity-into-meta-collection

call

list-entities-in-meta-collection

and match by entity id). If a previous attempt already succeeded, return the existing resource id instead of creating a duplicate. On retry after a transient error, prefer re-checking state over blindly re-issuing the create.

[MUST] User confirmation before any write — For any

update-*

,

create-*

,

add-entity-*

, or

register-*

(lineage) command, restate the exact target (Region / Project / Id / Name / new field values) to the user and obtain explicit confirmation BEFORE executing. Do not assume defaults; do not chain multiple writes without intermediate confirmation when the user has not pre-approved the full plan.

All CLI flags use kebab-case (lowercase with hyphens). Always use exactly the flag names shown in the command examples below. Key flags:

--page-size

,

--table-id

,

--src-entity-id

,

--dst-entity-id

,

--need-attach-relationship

,

--include-business-metadata

,

--meta-collection-id

,

--dataset-id

,

--project-id

,

--read-timeout

,

--connect-timeout

Entity IDs follow

${EntityType}:${InstanceId}:${CatalogId}:${DatabaseName}:${SchemaName}:${TableName}

. See

references/entity-id-formats.md

. Common MaxCompute:

maxcompute-table:::project_name::table_name

(no schema) or

maxcompute-table:::project_name:schema_name:table_name

(with schema). When user gives

project.table

, try no-schema first; if not found, retry with

default

schema.

Parameter confirmation — Confirm all user-customizable parameters (RegionId, entity IDs, etc.) before executing. Do NOT assume defaults.

Permission errors — Read

references/ram-policies.md

, guide the user to grant permissions, and wait for confirmation before retrying.

• Direct access — For MaxCompute, construct entity ID directly (

  maxcompute-table:::project::table

  ) and call

  get-table

  — no need to browse from catalogs.
• Lineage direction —

  --src-entity-id

  = downstream,

  --dst-entity-id

  = upstream. For full impact analysis, recursively query each downstream entity to trace multi-level lineage (ODS->DWD->DWS->ADS).
• Schema fallback — If MaxCompute table not found, retry with

  :default:

  schema (three-level model).
• Limits — Max 20 versions per dataset; Album operations require

  AliyunDataWorksFullAccess

  or creator/admin; max 2000 datasets per tenant.
• Deletions — Out of scope. If the user asks to delete a dataset/version/collection/lineage relationship or remove an entity from a collection, decline and tell them to use the DataWorks console.
• Retry safely — When a write times out or returns an ambiguous error, do NOT blindly retry. Re-check state with the matching

  list-*

  /

  get-*

  first to detect partial success, then decide whether to retry or accept.