/create-unstructured-workflow

name: create-unstructured-workflow
description: |-
  从一句业务需求（如"PPT 按页构建解决方案知识库"）出发，端到端创建 Dataphin 非结构化工作流：
  需求分析 → 算子链路设计 → 数据集设计与创建 → 工作流 JSON 组装 → create-work-flow-by-json 创建 → 输出验证指引。
  当用户场景涉及非结构化数据处理（文档解析 / 图片理解 / 音视频处理 / 知识库构建 / 向量化入库）或数据集增删改查时进入。

  触发词：非结构化工作流、创建工作流、知识库构建、文档解析、向量化、create-work-flow-by-json、unstructured workflow。

  关键限制：**仅支持离线（OFFLINE）**——实时工作流（TaskType=5/REALTIME 数据集）不在范围，Step 1 预检到即告知；仅 BASIC 项目（Env=PROD）；数据集 5 字段建后不可变；LLM/评分/去重算子不吃 URL 需桥接；环境值必须回读禁止编造；写操作前 HITL 确认。

创建 Dataphin 非结构化工作流（需求 → 数据集 → 工作流 → 验证）

1. Scenario Description

用户用一句业务需求触发（例："把 OSS 上的产品 PPT 按页解析，构建可检索的解决方案知识库"），本 skill 自动完成：

1. 需求分析（识别模态 + 格式兼容预检）； 2. 算子链路设计（输出设计稿，**暂停等用户确认**）； 3. 数据集准备（`list-datasets` 搜索复用 → 不存在则 `create-dataset` → `get-dataset` 回读）； 4. 组装工作流 JSON（算子骨架 + 回读环境值 + 业务定制提示词）； 5. `create-work-flow-by-json` 创建（默认测试模式 `TaskType=3 + Submit=false`）; 6. 输出三层验证指引（结构自检 → PipelineId → 界面回显 + 试跑）。

**Architecture**：`Dataphin Tenant + BASIC Project + Dataset(文件存储 OSS + 元数据存储 PG/Milvus) + 非结构化工作流(算子 DAG) + 模型实例(LLM/Embedding)`。

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（AK / STS / RamRoleArn 均可）；执行命令时用 `--profile <name>` 指定，缺省用默认 profile | | endpoint | 独立部署时必填 | 公共云用默认 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** (via `aliyun configure` in terminal or environment variables in shell profile) > 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.

| 参数 | 必填 | 描述 | 默认值 | |---|---|---|---| | `--op-tenant-id` | 是 | 租户 ID（大整数，shell 变量传递） | — | | ProjectId | 是 | BASIC 模式项目 ID | — | | 业务需求描述 | 是 | 一句话业务目标（决定模态与链路） | — | | 源数据格式 | 是 | 文件扩展名清单（决定格式兼容预检结果） | — | | 数据集名 / 表名 | 是 | 用户确认（表名须匹配 `^[a-z][a-z0-9_]{0,63}$`） | — | | TaskName / Directory | 是 | 工作流任务名 / 所属目录 | 测试目录 | | TaskType / Submit | 否 | 调度类型 / 是否提交 | `3`（手动）/ `false` |

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/create-unstructured-workflow/{session-id}

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

aliyun dataphin-public list-datasets --op-tenant-id "$TENANT_ID" \
  --dataset-query '{"ProjectId": 123, "Keyword": "知识库", "IncludeVersionList": true, "Page": 1, "PageSize": 10}' \
  --user-agent AlibabaCloud-Agent-Skills/create-unstructured-workflow/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

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

8. Core Workflow（六步流程）

TENANT_ID="30001011"        # 租户 ID
PROJECT_ID="789"            # BASIC 模式项目 ID
PROFILE="<aliyun configure list 中的有效 profile 名>"
SESSION_ID="<inherited from alibabacloud-dataphin-skills>"
UA="AlibabaCloud-Agent-Skills/create-unstructured-workflow/$SESSION_ID"

**本 skill 所有 `aliyun` API 命令统一携带 `--profile "$PROFILE"`（认证信息只来自 CLI 配置）；独立部署模式下按父 skill Step 0 约定另追加 `--skip-secure-verify`。**

**铁律：所有算子配置、字段结构、枚举值只能来自 `references/` 参考文档或 API 实时回读，禁止凭记忆编造。**

Step 1 需求分析（只读，不调 API）

1. **覆盖边界预检（先于一切，30 秒内给结论）**：出现下列任一信号——用户提“**实时**工作流”/要求 `TaskType=5`，或输入数据集 `Scenario=REALTIME`（元数据为 STREAM_TABLE 实时元表、无 MetadataStorageConfig）——**立即按实时能力边界处置**（见 §12 ✗ 平台限制）：有已有实时工作流可回读作基线 → 可走复刻/变体链路（[`references/realtime-workflow-notes.md`](references/realtime-workfl