alibabacloud-dataphin-skills

Dataphin Skill Suite

1. Installation (first step, prior to everything: pass the CLI version gate before reading the rest)

[MUST] The first thing to do upon entering this suite: first execute the "CLI version gate" script in §8 Step 0, step 0. The output must start with PASS ; if not PASS, no installation/configuration/business command below may be executed.

# 安装 aliyun CLI（>= 3.4.8）：https://github.com/aliyun/aliyun-cli
# 版本要求由 §8 Step 0 第 0 步「CLI 版本闸门」在每次会话开始时强制校验
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

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

# 验证
aliyun dataphin-public --help

See CLI installation guide。

2. Scenario Description

This suite is a collection of automation capabilities for the Dataphin product, adopting a "suite entry + sub-Skill" architecture:

Entry layer(this document): responsible for scenario routing and distribution, session-id generation, and credential pre-check
Module layer: grouped by business domain (dataplan/manage/dev/ops/dataservice/pipeline/assets/...)
Sub-Skill layer: each sub-Skill corresponds to one complete business scenario

All sub-Skills are located under the references/<模块>/<子skill>/ directory (such as references/dataplan/create-data-source/SKILL.md), and are loaded by this entry point according to the routing table.

Architecture

用户请求 → 套件入口（路由分发）→ 模块/子 Skill（业务执行）→ 验证结果

Current sub-Skill topology (two-level structure of module/sub-Skill):

dataplan/create-data-source — Create data source (87 types, including ConfigItemList configuration)
dataplan/check-data-source-connectivity — Data source connectivity check
dataplan/create-compute-source/create-maxcompute-compute-source — Create MaxCompute compute source
dataplan/update-compute-source — Update compute source
dataplan/check-compute-source-connectivity — Compute source connectivity check
dataplan/create-maxcompute-data-source — Create MaxCompute data source and verify connectivity
dataplan/create-project — Dataphin project creation requirement breakdown, public query, dependency verification, and whitelist management boundary check
dataplan/manage-project-member — Project member management (add/remove/update role/query list)
manage/manage-tenant-member — Tenant member management (add/remove/update role/query list)
manage/manage-row-level-permission — Row-level permission management (query/create/update/delete/reverse lookup by table or user/authorized account query)
manage/manage-column-permission — Column-level/field-level permission management (field authorization/revocation/record query/permission point verification)
dev/execute-ad-hoc-task — Ad hoc query task execution
dev/submit-batch-task — Submit offline batch task
dev/update-batch-task — Update offline batch task
dev/find-tenant-root-node — Find tenant virtual root node
dev/get-batch-task-info-by-name — Get batch task details by name
dev/get-bizdate — Get business date (bizdate)
dev/manage-resource-file — Resource file management (upload JAR/configuration files and create/update/query/delete Dataphin resources)
ops/create-node-supplement — Create backfill data task
ops/rerun-task-instance — Rerun task instance
ops/monitor-task-instance — Task instance monitoring and log query
ops/pause-task-instance — Pause/resume task instance
pipeline/create-pipeline-task — Create integration pipeline task (data synchronization)
pipeline/update-pipeline-task — Modify integration pipeline task configuration (scheduling/channel/component, query first then modify with full write-back)
assets/create-standard — Create data standard
assets/update-standard — Update data standard
assets/manage-data-standard — Data standard full lifecycle management (create/update/publish/offline/delete/query)
assets/manage-topic-domain — Subject domain full lifecycle management (query/create/update/delete, organize data warehouse layers)
assets/manage-biz-entity — Business entity full lifecycle management (query/create/update/publish/unpublish/delete of business objects/business activities)
assets/manage-biz-metric — Business metric definition management (create/update/draft and published state query/delete)
assets/develop-metric — Metric development (find source table → validate fields → create computation task → register custom metric → verify association)
assets/manage-asset-attributes — Asset custom attribute management (query attribute definitions + batch overwrite write of attribute values by GUID)
assets/query-asset-details — Asset catalog detail query (attributes/fields/usage instructions + data preview + lineage + quality overview, four sections)
assets/resolve-asset-guid — Asset GUID resolution (concatenate by type + read-back verification + search reverse lookup, providing prerequisites for sub-skills that require GUID)
assets/manage-lookup-table — Data standard code table management (create/query/update/delete, overall overwrite maintenance of code values)
assets/manage-standard-mapping — Standard mapping management (bidirectional field-standard query/batch mapping creation/invalidate/delete)
datasecurity/grant-data-source-permission — Grant data source authorization to production account
datasecurity/manage-data-classification — Data grading and classification management (grading/classification/field identification results/enable-disable cleanup)
datasecurity/manage-data-masking — Data masking requirement breakdown, field label prerequisite check, and public API boundary confirmation
dataservice/create-and-publish-api — Data service API creation and publishing
dataservice/manage-app-and-bindauth — Application management and API permission binding
dataservice/call-data-service-api — API invocation (zero-dependency Python script, sync/async/SSE)
dataservice/monitor-api-operations — Data service API operations monitoring (invocation summary, trend analysis, invocation logs, anomaly impact analysis)
knowledge-graph/manage-kg-schema — Knowledge graph ontology model management (Schema CRUD, import/export, publishing)
knowledge-graph/manage-kg-knowledge — Knowledge graph knowledge data management (entity-relationship CRUD, batch import)
knowledge-graph/query-kg — Knowledge graph graph data query (Cypher query, neighbor traversal, semantic search, purely read-only)
assets/configure-quality-rule — Configure full lifecycle of data quality rules (monitoring objects/rules/scheduling alerts/trial run/enable-disable/dashboard)
unstructured-data/create-unstructured-workflow — Create unstructured workflow (requirements → dataset → workflow → validation)
unstructured-data/update-unstructured-workflow — Update specified unstructured workflow (read-back → partial modification → submit → validation)
unstructured-data/create-dataset — Dataset full lifecycle management
unstructured-data/update-dataset-schema — Update dataset table structure (add columns/reload schema)

Knowledge graph sharing prerequisites: When a graph space is created, bind a graph engine (Neo4j / Lindorm),the engine determines the available query languages and modeling constraints(Lindorm does not support Cypher). Before entering any KG sub-skill, first read graph engine capability matrix and confirm the engine with the user.

3. Environment Variables

Variable	Description	Required
ALIBABA_CLOUD_ACCESS_KEY_ID	RAM AccessKey ID	Yes
ALIBABA_CLOUD_ACCESS_KEY_SECRET	RAM AccessKey Secret	Yes

Or configure the profile via aliyun configure .

4. Authentication

Pre-check: Credentials Required

Credentials must be confirmed available before execution:

aliyun configure list
aliyun dataphin-public --help

Validation criteria：

[MUST] CLI version gate has PASSED (script and decision rules see §8 Step 0, Step 0, this check has been moved forward to §8 Step 0, Step 0, and executes before all checks in this section)
aliyun configure list shows a valid profile
aliyun dataphin-public --help no errors

Pre-check: Aliyun CLI plugin update required

[MUST] First execute the "CLI version gate" script in §8 Step 0 Step 0, confirm the output starts with PASS (aliyun CLI >= 3.4.8); output FAIL It is forbidden to execute the following two commands and any subsequent operations; the CLI must first be upgraded and the gate rerun. [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.

4.1 Automatic environment determination (public cloud / standalone deployment)

This kit is asingle artifact, serving both public cloud and standalone deployment customers. When users call it directly, we do not know in advance which type they are,so the entry point must first automatically determine the environment—the type is always inferred from signals,and we never ask "are you public cloud or standalone deployment"。

[Hard rule] The environment type is completely invisible to the user：

Do not present a type-choice question (options such as "public cloud / standalone deployment / I'm not sure" are all forbidden).

The question text must also not contain the words "public cloud / standalone deployment", or wording such as "choose one of region (public cloud) / endpoint (standalone deployment)" that exposes the type dichotomy.

When collecting credentials for the first time,the first question only asks for AccessKey ID + AccessKey Secret, and must not mention region / endpoint at the same time. After the type is automatically determined from the AK, thenneutrallyask for the next item (only ask for region if determined to be public cloud, and only ask for endpoint if determined to be standalone deployment), so the user never perceives the concepts of "public cloud/standalone deployment" throughout.

For the complete determination and consumption logic, see version-aware OpenAPI reference. The following is an executive summary.

IMPORTANT: Before calling any sub-Skill, environment determination must be completed first.

[General rule] Reusing an existing profile must be echoed back: for any path that detects and reuses a profile thatalready existsfor the user (without creating a new configuration), the profile name used this time must be stated in the information given to the user (e.g. "this time using existing profile dataphin"); only when the profile is empty and the first-time collection process below is followed does this echo not apply. The echo must remain neutral and must not expose the deployment type.

Step-by-step collection on first use / when the profile is empty (strictly in order, without exposing the type)：

First question: only AK/SK. Ask the user for AccessKey ID + AccessKey Secret(the question must not contain any of the words region / endpoint / public cloud / standalone deployment). For safety, the user may also be allowed to aliyun configure on their own and then come back.
Automatic determination (after obtaining the AK, without asking): infer public cloud / standalone deployment according to the #2 prefix + #3 probe below.
Neutrally ask for the next item based on the determination result——Say only that one requesting sentence; no explanation, lead-in, or reason is allowed(words such as "public network/gateway/unrecognizable/private deployment/standalone deployment/public cloud/therefore/this means" must not appear; the word "AccessKey" itself may be used):
- Determined as public cloud → only ask:"Which region is your Dataphin in? For example cn-shanghai / cn-hangzhou." Then:
```
aliyun configure set --profile dataphin --mode AK \
  --access-key-id <AK> --access-key-secret <SK> --region <region>
```
- Determined as standalone deployment → only ask:"Please provide your Dataphin service address (endpoint), for example dataphin-openapi.xxx.com." Then:
```
aliyun configure set --profile dataphin-standalone --mode AK \
  --access-key-id <AK> --access-key-secret <SK> --endpoint <endpoint>
```

Counterexample (forbidden to say this): "This AccessKey cannot be recognized on the public network gateway, which means your Dataphin is privately deployed, so I also need the endpoint..." — any words explaining the determination process / pointing out the deployment form must not appear; simply ask for the endpoint plainly.

[Hard rule] The following determination signals are purely internal Agent reasoning and are completely invisible to the user throughout: Must not restate, explain, or inquire about any basis for determination to the user (such as endpoint hostname, AK prefix, probe results, "leaning toward public cloud/independent deployment", etc.). The Agent silently infers from high to low confidence, and once a match is found it is settled; only when necessary, neutrally ask about the missing item (region or endpoint), without revealing the inference process or the type of conclusion.

Custom endpoint already configured: The endpoint hostname in the profile / environment variables is not *.aliyuncs.com(such as dataphin-openapi.poc.lydaas.com）→ independent deployment。
AK prefix heuristic (zero cost): Public cloud AccessKeys basically start with LTAI ; independent deployment AKs are self-issued by Dataphin and usually are not LTAI。LTAI*→ leaning toward public cloud, not LTAI→ leaning toward independent deployment.
Cheap probe confirmation (authoritative): Use the current AK to make a published read-only call to dataphin-public.<region>.aliyuncs.com (when no region_id is available yet on first use, the probedefaults to cn-shanghai— the probe is only to verify whether the AK is recognized by the public network RAM, and is unrelated to the final region) — authentication passes/business error →public cloud；InvalidAccessKeyId→independent deployment; cannot connect to aliyuncs→leaning toward independent deployment, determined in conjunction with #2.
Only when it still cannot be determined, or when it has been judged as independent deployment but the user has not yet provided an endpoint → only then prompt to supply the endpoint (for independent deployment this is in any case a hard prerequisite for connecting to the gateway).

The above four signals and their determination conclusions are only used for internal routing,and must not appear in any reply to the user。

The environment type is always determined by the above signals atruntimeinferred (single artifact, no longer packaged by mode, and there is no deployment_mode configuration field).

[Hard rule] Environment lock (once determined, cannot be changed)：

Lock timing— meeting any one condition is deemed to mean the environment has been determined and locked, and cannot be changed within this session:

The user explicitly specified the environment, or provided an endpoint (= independent deployment) / provided only a region (= public cloud);

An existing profile was reused (dataphin → public cloud;dataphin-standalone or the endpoint hostname is not *.aliyuncs.com → independent deployment);

The determination signals #1~#3 above reached a conclusion.

Skip determination if already specified: When the environment has been explicitly specified by the user or the profile is already clear,no longer execute determination signals such as #2 AK prefix / #3 probe, and directly execute according to the specified environment.

Failure does not change the determination: After locking, any call failure (InvalidAccessKeyId / signature error / network unreachable / timeout / version retrieval failure, etc.) istroubleshot only within the current environment(check AK/SK, endpoint, OpTenantId, network); if troubleshooting is fruitless,directly throw the original error under that environment to the user and terminate。Strictly prohibitedRetrigger the environment determination due to failure,it is strictly forbidden to switch from the public cloud to standalone deployment, or from standalone deployment back to the public cloud and retry. The error message only presents the original error and troubleshooting suggestions, and likewise must not expose the deployment type.

Standalone deployment configuration guidance (the Agent must execute when determined to be standalone)

Check whether a profile named dataphin-standalone already exists:aliyun configure list
If already configured → first inform the user "This session uses the existing profile dataphin-standalone", then proceed to version retrieval (§4.2)

If not configured → collect from the user: service address endpoint, AccessKey ID, AccessKey Secret, then:

aliyun configure set --profile dataphin-standalone \
  --mode AK \
  --access-key-id <用户提供的AK> \
  --access-key-secret <用户提供的SK> \
  --endpoint <用户提供的endpoint>

Collect OpTenantId(tenant ID): under standalone deployment, the generic call for version retrieval, as well as the subsequentevery single aliyun dataphin-public command, all mandatorily require it. Ask neutrally "What is your tenant ID (OpTenantId)?", without explaining the reason. Record it in the session context for later use.
All subsequent commands append --profile dataphin-standalone(and see the rewriting rules below), thenyou must first go through §4.2 version retrieval + trimming + gate, before proceeding to routing。

Sub-Skill CLI command rewriting rules

Sub-Skill command templates keep the public cloud form; the Agent automatically appends under standalone mode:

--profile dataphin-standalone(route to the standalone deployment endpoint)
--skip-secure-verify(standalone deployment usually uses self-signed certificates)
--op-tenant-id <OpTenantId>(under standalone deploymentevery command is required, take the tenant ID collected in Step 0)

# 子 Skill 原始命令
aliyun dataphin-public create-data-source --body '...'
# Agent 在 standalone 模式下实际执行
aliyun dataphin-public create-data-source --body '...' --profile dataphin-standalone --skip-secure-verify --op-tenant-id <OpTenantId>

4.2 Version-aware 2.0 OpenAPI manifest (under standalone deployment, before routingmandatory gate）

Data file:references/config/openapi-2.0-versions.json(383 union entries, field min_version + channel）。

Public cloud: do not retrieve the version (GetServerVersion is not released, cannot be called, and is not needed). The manifest ≡ the set already published by the current gateway ≡ the installed dataphin-public plugin command set, all cli_command。

Standalone deployment: after confirming standalone deployment,before routing to any sub-Skill / collecting any business parameter / executing any interface, you must complete version retrieval → trimming → gate in order (it is strictly forbidden to skip directly into business parameter collection):

Retrieve version: call GetServerVersion to get the version string. It is sdk_only——has no CLI command, can only go throughgeneric call(see reference §4, POST + query parameters + required OpTenantId，V1 HMAC-SHA1）。Do not attempt aliyun dataphin-public get-server-version(that command does not exist)。
- Fallback: when the generic call fails for any reason (no output / Unknown API / signature error / network / timeout),do not silently assume the highest version and continue; instead, ask neutrally and directly "What version is your Dataphin? For example 6.0/6.1/6.2/6.3", and continue to Step 2 with the version given by the user.Version retrieval failure does not constitute a reason to change the environment determination— continue as standalone deployment (§4.1 environment locking), and do not switch back to the public cloud for a retry.
Normalize + clamp: remove the v prefix and take the first two major-version segments (v6.3.0.964601→6.3；6.2.2.1→6.2); clamp out-of-range values to 6.0~6.3。
Pruning: Load the data file, take the interfaces of min_version <= 归一版本 , and obtainthe set of interfaces valid in the current environment。
Version gate (critical, must be executed): The target interface requested by the user—whether it is the API behind a sub-Skill, or a cli_command used directly on a temporary basis such as CreateDataset —if its min_version > 归一版本(that is, it is not in the valid set) → stop immediately, clearly state "the current environment is version X, which does not support <the feature> (requires version Y+)",do not continue collecting parameters, do not execute. Only allow it when the target interface is in the valid set.
- Example: environment 6.0, user wants to "create a dataset" (CreateDataset min 6.2) → directly answer "the current environment 6.0 does not support creating datasets, requires 6.2 or above", and no longer collect parameters such as project-id / name.

By channel branch to generate the invocation method:

channel	Invocation method
`cli_command`	`aliyun dataphin-public <cli_command> …`(standalone appends `--profile dataphin-standalone --skip-secure-verify --op-tenant-id <OpTenantId>`）
`sdk_only`	generalized invocation / CommonRequest(RPC V1 signature, POST, authentication parameters placed in query, required `OpTenantId`）；cannot use CLI,`--force` also cannot(verified on real devices)

Rebuild the data file: executed by the maintainer in the internal build process build-openapi-version-index.sh(the script is not distributed with this skill). See version-aware OpenAPI reference。

5. RAM Policy

The suite-level RAM policy (the union of all sub-Skills) and the minimum permission grouping for each sub-Skill are uniformly maintained in RAM policy reference(the only permission declaration file for the entire suite); this file no longer maintains them inline, to avoid drift in two places.

Permission Failure Handling

If you encounter a permission error (HTTP 403 or ErrorCode containing Forbidden/NoPermission), please:

Confirm that the above policies have been attached to the RAM user
Confirm that the Resource scope in the policy covers the target tenant
Contact the tenant administrator for authorization

See RAM policy reference。

6. Parameter Confirmation

IMPORTANT: Parameter Confirmation Before routing to a sub-Skill, confirm the user's target scenario.

Please confirm the operation scenario you want to execute.

Version gating criteria (two sets of data with divided responsibilities, to avoid ambiguity)：

Runtime authoritative gate = references/config/openapi-2.0-versions.json(API level, determined by interface min_version ). In standalone deployment it is enforced by §4.2 , and is the sole basis for deciding "whether a scenario can be routed/executed".

references/config/version-manifest.json is only for skill-level coarse-grained registration(sub-Skill → minimum major version) and self-check list baseline,not used as a runtime gate。

In short: whether it can be routed is based on the openapi-2.0-versions.json in §4.2.

Scenario keywords	Target sub-Skill
create data source, new data source, add data source, ConfigItemList, JDBC	→ `create-data-source`
data source connectivity, check data source connection, test data source	→ `check-data-source-connectivity`
create compute source, new compute engine, MaxCompute compute source	→ `create-maxcompute-compute-source`
update compute source, edit compute source	→ `update-compute-source`
compute source connectivity, check compute source connection	→ `check-compute-source-connectivity`
create MaxCompute data source / connect MaxCompute / MC data source	→ `create-maxcompute-data-source`
Create project / new project / Dataphin project / project initialization / DevProd / Basic / project whitelist / project dependency	→ `create-project`
Project member / add member / remove member / update role / member management	→ `manage-project-member`
Tenant member / add tenant member / remove tenant member / update global role / tenant member management / tenant member	→ `manage-tenant-member`
Row-level permission, row permission, row permission, filter by row, control rule, authorized account, affected account	→ `manage-row-level-permission`
Column-level permission, field permission, field-level permission, column permission, field permission, sensitive field visibility, PHYSICAL_FIELD	→ `manage-column-permission`
Ad hoc query, execute SQL, temporary code run, create table	→ `execute-ad-hoc-task`
Submit offline task, task submission, submit-batch-task	→ `submit-batch-task`
Update task code, update scheduling, update-batch-task	→ `update-batch-task`
Virtual root node, NodeWithoutUpstream, attach default upstream, DagId	→ `find-tenant-root-node`
Query task by name, query task code, query task scheduling	→ `get-batch-task-info-by-name`
Business date, bizdate, T-1, today's date, yesterday	→ `get-bizdate`
Upload resource, resource file, UDF resource, JAR resource, create resource, create-resource, update-resource, get-resource, delete-resource	→ `manage-resource-file`
Data supplementation, supplemental run, backfill, rerun, supplement, backfill	→ `create-node-supplement`
Rerun instance / rerun / task rerun / operate-instance / instance recovery	→ `rerun-task-instance`
Instance status / view logs / task monitoring / instance monitoring / WAIT_SCHEDULE / FAILED / taskrun	→ `monitor-task-instance`
Pause instance / resume instance / pause / resume / pause scheduling / block scheduling	→ `pause-task-instance`
Data synchronization, data movement, pipeline, reader-writer, MySQL→MaxCompute	→ `create-pipeline-task`
Modify pipeline task, update pipeline, modify scheduling configuration, change cron, modify concurrency, modify dirty data, update-pipeline	→ `update-pipeline-task`
Create data standard, quality rule, create-standard	→ `create-standard`
Update data standard, update quality rule, update-standard	→ `update-standard`
Manage data standards, data standard lifecycle, publish standard, offline standard, delete standard, standard list	→ `manage-data-standard`
Manage subject domain, subject domain lifecycle, create/modify/delete subject domain, subject domain list, data warehouse layering, create subject domain under data domain	→ `manage-topic-domain`
Manage business entity, business object, business activity, create/modify/publish/offline/delete business entity, dimensional modeling, fact modeling, business model	→ `manage-biz-entity`
Manage business metric, business caliber, metric definition, create/modify/query/delete business metric, GMV, DAU, conversion rate, metric relationship diagram	→ `manage-biz-metric`
Develop metric, create technical metric, custom metric, develop metric from table, metric calculation task, register custom metric	→ `develop-metric`
Code table, standard code, code value, code value, lookup table, create code table, maintain code value	→ `manage-lookup-table`
Standard mapping, standard mapping, mapping relationship, field association standard, valid mapping, invalid mapping, unmap	→ `manage-standard-mapping`
Asset GUID, how to assemble guid, assemble GUID, cannot find GUID in the UI, TableGuid, AssetGuid, dp_table, dp_ds_table, odps., dp_index, cust_index, biz_index, dp_api, qbi_page, asset unique identifier	→ `resolve-asset-guid`
Data source authorization, production account authorization, DsRead, DsWrite, PublishStatus=0	→ `grant-data-source-permission`
Data grading and classification, classification and grading, data classification, data grading, security level, sensitive data label, recognition result, C1, C2, C3, C4	→ `manage-data-classification`
Data masking, masking rules, dynamic masking, field masking, phone number masking with asterisks, ID card masking, email masking, whitelist, masking, desensitize	→ `manage-data-masking`
Create API, publish API, SQL API, API development	→ `create-and-publish-api`
Create application, API authorization, permission binding, application management	→ `manage-app-and-bindauth`
Call API, SDK call, Python call	→ `call-data-service-api`
API monitoring, call logs, operations analysis	→ `monitor-api-operations`
Knowledge graph Schema, ontology model, entity types, relationship types, Schema publishing	→ `manage-kg-schema`(First confirm the graph engine: the available set of dataType varies by engine)
Knowledge graph data, create entities, create relationships, batch import	→ `manage-kg-knowledge`(CRUD is engine-agnostic)
Knowledge graph query, Cypher query, neighbor traversal, graph query, relationship path, semantic search	→ `query-kg`（First confirm the graph engine: Cypher is Neo4j only)
Quality monitoring, quality rules, data quality validation, quality alerts, quality trial run, quality scheduling, monitoring objects	→ `configure-quality-rule`
Unstructured workflow, create workflow, knowledge base construction, document parsing, vectorization	→ `create-unstructured-workflow`
Update workflow, modify workflow, adjust operators, change prompts, update-pipeline	→ `update-unstructured-workflow`
Create dataset, dataset management, metadata table, vector table	→ `create-dataset`
Update dataset table schema, add columns to dataset, modify metadata table, update-dataset-schema	→ `update-dataset-schema`

7. Observability

The single source of truth for the suite release version is references/manifest.json in version field (SemVer); on release, update the version only in that file.references/config/version-manifest.json in min_version / default_min_version is the Dataphin server-compatible version and cannot be used for UA.

The parent layer generates the session-id only once (32-character lowercase hexadecimal) and the entire suite reuses it.

Set SUITE_ROOT to the actual absolute directory where this SKILL.md is located (located by the currently loaded file, not dependent on the working directory), then perform the following initialization. Usecommon UA helper to validate the manifest; if the file is missing or the version is empty/invalid, stop API calls and do not guess the version or omit the suffix.

SESSION_ID=$(python3 -c "import uuid; print(uuid.uuid4().hex)")
SKILL_VERSION=$(python3 "$SUITE_ROOT/references/scripts/skill_user_agent.py" --version) || exit 1
UA=$(python3 "$SUITE_ROOT/references/scripts/skill_user_agent.py" --session-id "$SESSION_ID") || exit 1

API commands of all parent and child Skills must carry (the entire UA is a single quoted parameter):

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}"

In Shell, write --user-agent "$UA", and do not combine a flag and its value in a variable and then perform unquoted expansion.{version} must be replaced with the SKILL_VERSIONread from the manifest, and the session placeholder in the example must also be replaced with the current value.configure / plugin / version except for local tool commands such as these.

Child Skills inherit the parent layer's session-id, SKILL_VERSION, UA, and SUITE_ROOT, and do not regenerate them or change them to the child skill name. When loading a child Skill directly, first perform the initialization in this section; for cross-Shell calls, the Agent re-injects the saved values and does not depend on the previous Shell's environment. In the SDK script, pass SKILL_SESSION_ID="$SESSION_ID" python3 ...inline; the temporary SDK template must also pass SUITE_ROOT="$SUITE_ROOT" to load the common helper. The SDK reads the manifest directly; degrading without a session-id or hand-writing the version is prohibited.

8. Core Workflow (scenario routing table dispatch)

Step 0: Version retrieval and gating (must be executed first in every session, cannot be skipped)

Order: ⓪ CLI version gate → ① Accept only AK/SK → ② Automatically determine from AK → ③ Based on the determination result, neutrally ask for the next item; throughout the process, do not expose the concepts of "public cloud/independent deployment" to the user.

CLI version gate ([hard rule] cannot be skipped; no subsequent step may be executed unless PASS): Before entering the remaining steps of this Step (credential check, environment determination, routing, business parameter collection),you must first execute as-isthe following script and determine based on the output:
```
REQUIRED=3.4.8
CURRENT=$(aliyun version 2>/dev/null | head -n1 | tr -d '[:space:]')
if [ -z "$CURRENT" ]; then
  echo "FAIL: aliyun CLI 未安装"
elif [ "$(printf '%s\n' "$REQUIRED" "$CURRENT" | sort -V | head -n1)" = "$REQUIRED" ]; then
  echo "PASS: aliyun CLI $CURRENT (>= $REQUIRED)"
else
  echo "FAIL: aliyun CLI $CURRENT < $REQUIRED，必须先升级"
fi
```
- Determination rule：Only when the output starts with PASS may you continue; if the output is FAIL, the script produces no output, or execution errors, it is uniformly regarded as not passed. Visually comparing version numbers in place of this script is prohibited.
- Failure action (when not passed)：
  - Stop immediately, and do not enter credential check, environment determination, routing, or any business parameter collection;
  - Explain to the user the current version and the required version (3.4.8), and provide the upgrade method (see the one-click installation script for the corresponding operating system in CLI Installation Guide ),and execute the upgrade only after user confirmation(upgrades are system changes and follow the §12 HITL principle; do not perform silent automatic upgrades);
  - After the upgrade/installation is completeyou must rerun this gate script, and only if the output is PASS may you proceed to Step 1; if it is still FAIL , then throw the original output to the user and terminate.
aliyun configure list Check whether valid credentials already exist.Credentials exist (reuse the existing profile) → first echo back to the user the profile name used this time, then continue, for example "This time using existing profile <name> to continue the operation", then skip to Step 3 to perform environment determination. Keep the echo wording neutral; only state which profile was used, do not explain the determination process, and do not expose the deployment type.
No credentials (first use / empty profile) First question: ask the user only for AccessKey ID + AccessKey Secret. In the question wording,must not appear any of the words region / endpoint / public cloud / independent deployment. (Security-optional: the user may also aliyun configure on their own and come back.)
Automatically determine after obtaining the AK (do not ask): According to §4.1 use #1 endpoint / #2 AK prefix / #3 probe (first time default cn-shanghai) to infer the environment.
Based on the determination result, neutrally ask for the next item and write the profile——Say only the sentence asking for it; explaining the reason / pointing out the deployment form is prohibited(the words public network / gateway / unrecognizable / private deployment / independent deployment / public cloud, etc. must not appear; the word "AccessKey" itself may be used):
- Determined as public cloud → ask only "Which region is your Dataphin in? For example cn-shanghai / cn-hangzhou." → aliyun configure set --profile dataphin --mode AK --access-key-id <AK> --access-key-secret <SK> --region <region>, then directly enter Step 1.
- Determined as independent deployment → ask only "Please provide your Dataphin service address (endpoint), for example dataphin-openapi.xxx.com." → aliyun configure set --profile dataphin-standalone --mode AK --access-key-id <AK> --access-key-secret <SK> --endpoint <endpoint>; and guide according to the §4.1 independent deployment configurationCollect OpTenantId(tenant ID). In this session,all aliyun dataphin-public commands must be appended with:
```
--profile dataphin-standalone --skip-secure-verify --op-tenant-id <OpTenantId>
```
[Hard rule] Environment lock: The determination conclusion in Step 3 (or the environment explicitly specified by the user / already established by an existing profile) is theenvironment locked for this session. When any subsequent step (including the §4.2 version gate and sub-Skill execution) fails,the environment must not be re-adjudicated—you must not switch from the public cloud to a standalone deployment, nor switch from a standalone deployment back to the public cloud; troubleshoot only within the current environment, and if troubleshooting yields no result, throw the original error to the user and terminate (see §4.1 Environment lock）。
Standalone deployment mandatory gate (cannot be skipped): After completing the above configuration and before entering routing,you must first execute §4.2 version retrieval → trimming → gate. It is strictly forbidden to skip version retrieval and directly enter business parameter collection; if the interface requested by the user is min_version higher than the current environment version, you must directly inform them at this gate that it is not supported and stop. (The public cloud does not have this gate; proceed directly to Step 1.)

Step 1~5: Scenario routing

Identify scenario keywords: Extract keywords from the user request
Version gate(standalone deployment only, already enforced in Step 0 step 5): The target interface must have passed the §4.2 version gate (min_version <= 当前环境版本) before it can be routed; interfaces not in the valid set (such as CreateDatasetfor the 6.0 environment) should already have been blocked at the gate and informed "Y+ version required", and must not enter the routing/parameter collection below
Match routing table：

Keyword	Routing target
Which interfaces are supported / interface list / current version / whether a certain interface can be used / APIs supported by the version	§4.2 Version-aware list (handled inline at the parent layer, does not route to a sub-Skill) → Reference
Create data source / new data source / add data source / ConfigItemList / JDBC / data source type	create-data-source
Data source connectivity / check data source connection / test data source	check-data-source-connectivity
Create compute source / new compute engine / MaxCompute compute source	create-maxcompute-compute-source
Update compute source / edit compute source	update-compute-source
Compute source connectivity / check compute source connection	check-compute-source-connectivity
Create MaxCompute data source / connect MaxCompute / MC data source / MaxCompute datasource	create-maxcompute-data-source
Create project / new project / Dataphin project / project initialization / DevProd / Basic / project whitelist / project dependencies	create-project
Project members / add members / remove members / update roles / member management	manage-project-member
Ad-hoc query / execute SQL / run code temporarily / create table / execute-ad-hoc-task	execute-ad-hoc-task
Submit offline task / task submission / submit-batch-task	submit-batch-task
Update task code / update scheduling / update-batch-task	update-batch-task
Virtual root node / NodeWithoutUpstream / attach default upstream / DagId	find-tenant-root-node
Query task by name / query task code / query task scheduling / get-batch-task-info-by-name	get-batch-task-info-by-name
Business date / bizdate / T-1 / today's date / yesterday	get-bizdate
Upload resource / resource file / UDF resource / JAR resource / create-resource / update-resource / get-resource / delete-resource	manage-resource-file
Data supplementation / backfill run / backfill / rerun / supplement / backfill	create-node-supplement
Rerun instance / rerun / task rerun / operate-instance / instance recovery	rerun-task-instance
Instance status / view logs / task monitoring / instance monitoring / WAIT_SCHEDULE / FAILED / taskrun	monitor-task-instance
Pause instance / resume instance / pause / resume / pause scheduling / block scheduling	pause-task-instance
Data synchronization / data movement / pipeline / reader-writer / MySQL→MaxCompute	create-pipeline-task
Modify pipeline task / update pipeline / modify scheduling configuration / change cron / modify concurrency / modify dirty data / update-pipeline	update-pipeline-task
Create data standard / quality rule / create-standard	create-standard
Update data standard / update quality rule / update-standard	update-standard
Manage data standards / data standard lifecycle / publish standard / unpublish standard / delete standard / standard list query	manage-data-standard
Manage subject domains / subject domain lifecycle / create / modify / delete subject domain / subject domain list / data warehouse layering / create subject domain under data domain	manage-topic-domain
Manage business entities / business objects / business activities / business entity lifecycle / create / modify / publish / unpublish / delete business entity / dimensional modeling / fact modeling	manage-biz-entity
Manage business metrics / business definitions / metric definitions / create / modify / query / delete business metric / GMV / DAU / conversion rate / metric relationship diagram	manage-biz-metric
Develop metric / create technical metric / custom metric / develop metric from table / metric computation task / register custom metric / develop metric	develop-metric
Code table / standard code / code value / code value / lookup table / create code table / maintain code values / create-standard-lookup-table	manage-lookup-table
Standard adoption / standard mapping / mapping relationship / field association standard / valid mapping / invalid mapping / remove mapping / create-standard-mapping	manage-standard-mapping
Asset attributes / custom attributes / attribute write-back / batch update attributes / asset tagging / update-asset-attributes / AssetAttribute	manage-asset-attributes
Asset GUID / how to compose guid / compose GUID / cannot find GUID in UI / TableGuid / AssetGuid / dp_table / dp_ds_table / odps. / dp_index / cust_index / biz_index / dp_api / qbi_page / asset unique identifier	resolve-asset-guid
Asset details / asset profile / asset attribute query / field list / usage instructions / data preview / first 50 rows / lineage / upstream and downstream / field lineage / quality overview / quality score / directory hierarchy / asset mounted directory / topic / DirectoryChain	query-asset-details
Tenant members / add tenant member / remove tenant member / update global role / tenant member management / tenant member	manage-tenant-member
Row-level permission / row permission / row permission / row-level permission / filter by row / control rule / authorized account / affected account	manage-row-level-permission
Column-level permission / field permission / field-level permission / column permission / field permission / sensitive field visibility / PHYSICAL_FIELD	manage-column-permission
Data source authorization / production account authorization / DsRead / DsWrite / PublishStatus=0	grant-data-source-permission
Data classification and grading / classification and grading / data classification / data grading / security level / sensitive data label / recognition result / C1 / C2 / C3 / C4	manage-data-classification
Data masking / masking rule / dynamic masking / field masking / mask phone number with asterisks / ID card masking / email masking / whitelist / masking / desensitize	manage-data-masking
Create API / Publish API / SQL API / API development / Data service API	create-and-publish-api
Create application / API authorization / Permission binding / Application management / Key	manage-app-and-bindauth
Call API / SDK call / Python call / AppKey	call-data-service-api
API monitoring / Call logs / Operations analysis / Anomaly analysis	monitor-api-operations
Knowledge graph Schema / Ontology model / Entity type / Relationship type / Schema import and export / Schema publishing	manage-kg-schema
Knowledge graph data / Create entity / Create relationship / Batch import	manage-kg-knowledge
Knowledge graph query / Cypher query / Neighbor traversal / Graph query / Relationship path exploration / Semantic search	query-kg
Knowledge graph engine differences / Neo4j vs Lindorm / Why does Cypher report an error / Property type support	Graph engine capability matrix
Quality monitoring / Quality rules / Data quality validation / Quality alerts / Quality trial run / Quality scheduling / Monitoring objects	configure-quality-rule
Unstructured workflow / Create workflow / Knowledge base construction / Document parsing / PPT by page / Vectorization / Embedding ingestion / create-work-flow-by-json	create-unstructured-workflow
Update workflow / Modify workflow / Adjust operators / Change prompts / Switch models / Add or remove operators / update-pipeline	update-unstructured-workflow
Create dataset / New dataset / Dataset management / Metadata table / Table schema design / Vector table / Milvus / create-dataset / list-datasets / Dataset	create-dataset
Update dataset table schema / Add columns to dataset / Modify metadata table / Reload table schema / ALTER TABLE dataset / update-dataset-schema	update-dataset-schema

Load sub-SKILL.md: Delegate execution, passing session-id, SKILL_VERSION, UA, and SUITE_ROOT
Report results: Return an execution summary after the sub-Skill completes

Step 0–5 input/output examples and edge cases

The following are fictional documentation walkthrough examples, not actual execution results, and are not used as default values for user parameters; environment determination and session identifiers are internal context, and the neutral expression rules in §4.1 are still followed when replying to users.

Step	Example input	Expected output	Edge cases and handling
Step 0: Pre-checks and environment locking	CLI version is `3.4.8`, a valid profile exists `dataphin-standalone`, server version obtained `6.3`	Version gate output `PASS: aliyun CLI 3.4.8 (>= 3.4.8)`; echo "This time using existing profile `dataphin-standalone`"; internally lock the environment and, according to `6.3` trim the API set	Stop if the gate is not PASS; when there is no valid profile, complete configuration step by step per §4.1; when version retrieval fails, ask for the version, do not guess, and do not switch environments
Step 1: Identify the scenario	The user says "help me create a dataset"	Internally extract the keyword "create dataset"	When the user only says "help me process data", neutrally ask for the specific operation, and do not choose a business scenario on your own
Step 2: API version gating	Version locked `6.3`, target `CreateDataset` minimum version is `6.2`	The target API is in the valid set; routing may continue	If the version is `6.0`, reply "The current version 6.0 does not support creating datasets; version 6.2 or above is required", stop accepting parameters and stop execution
Step 3: Route matching	Keyword "create dataset", version gate passed	The only target is `references/unstructured-data/create-dataset/SKILL.md`	When multiple scenarios are hit, confirm the intent first; when there is no match, state that no corresponding guidance was found, and do not fabricate a path
Step 4: Load and pass through	The target document is readable; the parent layer has already initialized session-id `0123456789abcdef0123456789abcdef`, and saved `SKILL_VERSION`、`UA`、`SUITE_ROOT`	Load the target sub-Skill; inherit the same session-id, version, UA, and suite path, and enter the sub-Skill's parameter confirmation process	If the document is missing or unreadable, stop; if not initialized, complete §7 first; across Shells, re-inject the saved value and do not regenerate the session-id
Step 5: Report the result	The sub-Skill returns "Dataset demo_orders created, read-back verification passed"	Reply "Dataset demo_orders created, read-back verification passed."	When only document analysis is completed, reply "Guidance file located, creation not yet executed"; when execution fails or is unverified, state it truthfully and do not claim success

9. Success Verification

Routing and dispatch success criteria:

CLI version gate has PASSED (§8 Step 0, step 0)
Keyword match hits and is unique
The sub-SKILL.md file exists and is readable
Session-id has been generated and passed

10. Cleanup

Each sub-Skill is responsible for its own resource cleanup; see §10 of the corresponding sub-Skill for details.

11. Command Tables

See Related command index。

12. Best Practices

Large integer IDs (19-digit snowflake) must be passed as strings; in examples, wrap them in quotes
Write operations (create/update/delete/grant/publish) must have HITL confirmation before execution
Do not pass --mode AK and business parameter --modeat the same time ([verified by testing]): for some commands (such as list-projects), the business parameter --mode(project mode BASIC/DEV_PROD) conflicts by having the same name as the global authentication parameter --mode（AK/StsToken）same-name conflict; when they appear together, it directly reports ERROR: parse failed --mode duplicated. When you need to specify the business --mode , switch credentials to environment variable ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET injection, and do not write it on the command line --mode AK --access-key-id ...
list-projects 's --mode is actually required([verified by testing,--help marked as optional]): when not passed, the server reports DPN.Project.EnumNotFound：枚举ModeEnum不存在. Moreover, BASIC and DEV_PROD are two disjoint result sets; to enumerate all projects, you must query once in each of the two modes
Default Endpoint rules for independently deployed environments:
- Management plane OpenAPI:dataphin-openapi.<env>.aliyun.com
- Data service gateway:dataphin-os-gateway.<env>.aliyun.com
After each operation is completed, use the list-* command to query back and confirm
Context economy (a must-read for read-only queries): the complete return of metadata/list-type read-only commands is often extremely large (measured get-table-columns a single table reached 18k characters; one round of exploration tool output was 103k characters ≈ 41k tokens, of which 68% came from untrimmed field lists). You must:
- When querying fields/lists, include --cli-query '<JMESPath>' to take only the needed fields (such as ColumnList[].{Name:Name,DataType:DataType,Cn:Cn}, measured reduction of ~86%)
- list-tables must include --cli-query 'PageResult.TableList[].Name': if omitted, it returns the full metadata of over twenty fields for each table,measured at 115k characters in a single call (39% of a single-turn context); also: this command uses flat parameters --catalog/--keyword/--page-no/--page-size，there is no --list-query(passing it incorrectly yields an empty result)
- For paginated interfaces, given --page-size, do not pull the full set by default;first fetch --cli-query 'PageResult.TotalCount' to determine the total count before deciding whether to page through, and do not retry empty pages(measured: once retried pages 2/3 that had already been fully fetched 5 times for nothing)
- Log-type interfaces (get-ad-hoc-task-log / get-physical-instance-log）pull only on failure or when status confirmation is needed, first fetch only the status field, and when viewing the body, fetch it and take the tail fragment
- Do not query the same object repeatedly (reuse an existing response; do not first get-table-columns then DESC 表）
- Do not pull bare aliyun dataphin-public --help(full command help measured at 44.5k characters); when looking for a command name, just search command names by keyword. Knowncode tables/standard sets/standard templates all have no list-type commands(only by ID get-*), do not look for list-standard-sets、list-standard-templates or similar nonexistent commands
Deployment mode related：
- Sub-Skills are unaware of the deployment mode; all endpoint adaptation is driven by the parent-layer profile configuration
- The environment (public cloud / standalone deployment) is automatically determined at runtime by §4.1 runtime automatic determination(endpoint / AK prefix / probing), no longer relying on deployment_mode field, and does not ask the user for type
- Once the environment is locked, it cannot be switched(§4.1 hard rule): when a call fails, troubleshoot only within the current environment or directly throw the original error and terminate; do not perform cross-environment fallback retries between public cloud ↔ standalone deployment
- The standalone deployment interface list is trimmed according to §4.2 version awareness; unpublished sdk_only interfaces can only be called generically