/update-dataset-schema

name: update-dataset-schema
description: |-
  更新 Dataphin 非结构化数据集的元数据表结构（加列/改列）。核心约束：**表结构不能在线编辑**——
  正确流程是「即席查询执行 ALTER SQL 改库表 → update-dataset 重新提交表结构 → 回读验证」三段式。
  当用户场景涉及数据集表结构变更（加字段/加向量列/改注释）、"数据集表结构怎么改"、"重新加载表结构"时进入。

  触发词：更新数据集表结构、数据集加列、修改元数据表、加字段、重新加载表结构、ALTER TABLE 数据集、
  update-dataset-schema、表结构变更。

  关键限制：表结构无在线编辑入口，必须 SQL + 重新提交两步走；Milvus 不支持 DDL（仅 PG/Lindorm 适用）；
  已有工作流引用的列禁止删改（只加不减最安全）；写操作前必须 HITL 确认。

更新数据集表结构（ALTER SQL → 重新提交 schema → 回读验证）

1. Scenario Description

数据集的元数据表结构**不能在线编辑**（界面与 OpenAPI 均无直接改列入口）。变更表结构（典型：为多列输出加字段、补 URL 桥接列、加向量列）必须三段式：

1. **即席查询执行数据库 SQL**（`execute-ad-hoc-task`，DATABASE_SQL 类型直连元数据 PG 数据源）改物理表结构； 2. **数据集重新提交表结构**（`update-dataset` 携带与库中一致的完整 TableSchema，等价于界面"重新加载表结构"）； 3. **回读验证**（`get-dataset` / `list-datasets` 核对列清单与物理表一致）。

**Architecture**：`Dataphin Project + Dataset(版本级 TableSchema) + 元数据存储数据源(PostgreSQL) + 即席查询(DATABASE_SQL 通道)`。

**上下游衔接**：常由 `create-unstructured-workflow`（经套件入口路由加载） 的链路改造触发（如 LLM 算子改多列输出需为每个 customOutputColumns 字段加表列）。

2. Installation

aliyun plugin install --names aliyun-cli-dataphin-public

（详见 [`references/cli-installation-guide.md`](references/cli-installation-guide.md)）

3. Environment Variables

**认证信息统一使用阿里云 CLI 配置（profile）：凭证预先通过 `aliyun configure --profile <name>` 配置，本 skill 不直接读取 AK/SK 环境变量或任何本地文件。**

| 配置项 | 必填 | 说明 | |---|---|---| | CLI profile | 是 | `aliyun configure list` 中的有效 profile；执行命令时用 `--profile <name>` 指定 | | endpoint | 独立部署时必填 | 独立部署/POC 环境由父 skill Step 0 配置专用 profile（含 endpoint）并统一透传 | | `DATAPHIN_PROFILE` | 否 | 多租户场景下的 dataphin 本地 profile 名（`--dataphin-profile`） |

4. Authentication

> **Pre-check: Alibaba Cloud Credentials Required** > > **Security Rules:** > - **NEVER** read, echo, or print AK/SK values > - **NEVER** ask the user to input AK/SK directly in the conversation or command line > - **NEVER** use `aliyun configure set` with literal credential values > - **ONLY** use `aliyun configure list` to check credential status > > ```bash > aliyun configure list > ``` > Check the output for a valid profile (AK, STS, or OAuth identity). > > **If no valid profile exists, STOP here.** > 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak) > 2. Configure credentials **outside of this session** > 3. Return and re-run after `aliyun configure list` shows a valid profile

**Pre-check: Aliyun CLI >= 3.4.8 required** > Run `aliyun version` to verify >= 3.4.8. If not installed or version too low, > see `references/cli-installation-guide.md` for installation instructions.

**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.

5. RAM Policy

最小权限策略详见 [`../../ram-policies.md`](../../ram-policies.md)。

> **[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

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.

**固定参数检查与映射**（三档策略：明确映射直接用 / 环境可推断给候选待确认 / 缺失向用户索要，不猜不编造）：

| 参数 | 必填 | 收集策略 | |---|---|---| | 目标数据集 | 是 | 给了名称 → `list-datasets --keyword` 反查；给了 ID → 直接回读 | | 目标版本/表 | 是 | 从回读的 VersionList 列出候选（版本号+表名）让用户选 | | 元数据数据源 ID / Schema | 自动 | 从回读的 `MetadataStorageConfig.DataSourceId/ProdSchema` 取，**不询问** | | 变更内容 | 是 | 用户给出加哪些列（名/类型/注释）；服务于工作流改造时按算子输出字段自动设计待确认 | | 执行项目 | 是 | 即席查询所在项目（默认数据集所属项目，需用户确认有权限） |

7. Observability (MUST follow for every aliyun command)

**session-id 由父 skill `alibabacloud-dataphin-skills` 在套件入口加载时生成（32-char 小写 hex），本子 skill 加载时直接继承同一 session-id，不再重新生成。**

**Rule: Every `aliyun` CLI command that calls a cloud API MUST include the `--user-agent` flag.** Local utility commands (e.g. `configure`, `plugin`, `version`) do not support this flag and should be excluded.

--user-agent AlibabaCloud-Agent-Skills/update-dataset-schema/{session-id}

Example (assuming session-id is `a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`):

aliyun dataphin-public get-dataset --op-tenant-id "$TENANT_ID" \
  --project-id "$PROJECT_ID" --id "12345" \
  --user-agent AlibabaCloud-Agent-Skills/update-dataset-schema/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Do not skip, alter the format, or omit `--user-agent` on any `aliyun` API command invocation.

8. Core Workflow（三段式）

TENANT_ID="30001011"
PROJECT_ID="789"
PROFILE="<aliyun configure list 中的有效 profile 名>"
SESSION_ID="<inherited from alibabacloud-dataphin-skills>"
UA="AlibabaCloud-Agent-Skills/update-dataset-schema/$SESSION_ID"

**本 skill 所有 `aliyun` API 命令统一携带 `--profile "$PROFILE"`；独立部署模式下按父 skill Step 0 约定另追加 `--skip-secure-verify`。**

Step 1 回读现状 + 变更设计稿（⏸ 暂停等用户确认）

# 回读数据集：拿 MetadataStorageConfig（DataSourceId/ProdSchema/TableName/TableSchema）与 FileId
aliyun dataphin-public list-datasets --op-tenant-id "$TENANT_ID" --project-id "$PROJECT_ID" \
  --keyword "<数据集名>" --include-version-list true --page 1 --page-size 10 \
  --profile "$PROFILE" --user-agent "$UA"

产出**变更设计稿**并经用户确认：

• 现状列清单 vs 目标列清单 diff（只加不减最安全）；
• 对应 ALTER SQL（如 `ALTER TABLE public.<表名> ADD COLUMN <列> <类型>; COMMENT ON COLUMN ... IS '...';`）；
• 变更后的**完整** `TableSchema.Columns`（含既有列 + 新列，与库中最终结构逐列一致）；
• **前置自查**：该数据集版本被哪些工作流引用（OpenAPI 无引用查询，界面确认或询问用户）——已被引用的列**禁止删改**。

Step 2 即席查询执行 ALTER SQL（写操作，HITL 确认后执行