alibabacloud-flink-workspace-ops

阿里云 Flink 控制台运维

通过 CLI 操作控制台工作区资源： python scripts/flink_ververica_ops.py <command> [args]

强制执行规则：触发此技能时，必须使用 python scripts/flink_ververica_ops.py 执行实际 CLI 命令。绝不能创建 Shell 脚本、文档或 Markdown 文件来替代实际命令执行。绝不能使用 aliyun emr、aliyun ververica、kubectl 或任何其他 CLI——只能使用 python scripts/flink_ververica_ops.py。绝不能输出“基线运行”“未使用任何技能”或“模拟”等措辞。

阿里云 CLI（aliyun）的 AI 模式配置

此技能直接使用阿里云 Python SDK（而非阿里云 CLI）。如果用户的环境也会将阿里云 CLI（aliyun）用于其他用途，请确保插件为最新版本：

# Update plugins to latest version
aliyun plugin update
# Plugin mode examples (lowercase-hyphenated, never PascalCase)
aliyun ram list-policies-for-user --user-name <user_name>
aliyun ram list-access-keys --user-name <user_name>

可观测性（每次 aliyun 命令都必须遵循）

加载此技能时，生成一个随机会话 ID（32 位小写十六进制字符串），在整个会话中仅生成一次。下文将其用作 {session-id}。

规则：每条调用云 API 的 aliyun CLI 命令都必须包含 --user-agent 标志。 本地实用程序命令（例如 configure、plugin、version）不支持此标志，应排除在外。

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-flink-workspace-ops/{session-id}

示例（假设 session-id 为 a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6）：

aliyun ecs describe-instances --biz-region-id cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-flink-workspace-ops/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

调用任何 aliyun API 命令时，都不得跳过、修改格式或省略 --user-agent。

脚本 / Terraform 执行：运行 Python SDK 脚本、Terraform 命令或 Bash 脚本时，通过内联环境变量注入 session-id，以便代码在运行时读取：

# Python SDK script (this skill's CLI)
SKILL_SESSION_ID={session-id} python scripts/flink_ververica_ops.py <command> [args]

# Terraform
SKILL_SESSION_ID={session-id} terraform apply

脚本和 Terraform 配置应从环境变量读取 SKILL_SESSION_ID（如果不存在，则默认为空字符串）。此技能的 scripts/client.py 会读取 SKILL_SESSION_ID，并将 SDK 的 user_agent 设置为 AlibabaCloud-Agent-Skills/alibabacloud-flink-workspace-ops/{session-id}，确保 CLI、SDK 和 Terraform 通道使用相同的 session-id。

范围与边界

适用范围：Flink 控制台工作区运维——SQL 草稿、SQL 验证、部署 / 作业、Session 集群、工作区成员 / 变量、目录 / 数据库 / 表、作业诊断。

不在适用范围内（请勿处理）：

• 实例生命周期（创建 / 扩缩容 / 删除 / 续费）→ 使用 alibabacloud-flink-instance-manage
• 容器 / Pod 故障排查
• 对象存储上传 / 下载
• 其他计算引擎的集群管理
• 在用户服务器上安装开源框架
• 通用云基础设施（计算 / 网络 / 计费）
• 软件包上传 / 提交操作

触发条件（重要）

当请求涉及 Flink / Ververica 控制台工作区运维，并且符合以下一项或多项条件时，触发此技能：

1. 操作关键词：draft、SQL、validate、deployment、job、Session Cluster、namespace、table、member、variable、checkpoint。
2. 资源 ID 格式：w-*、d-*、j-*、sc-*、draft-*。
3. 属于适用范围的 Flink 控制台测试意图：生命周期流程验证、安全护栏验证、参数验证。

对于没有 Flink 控制台上下文的通用云相关提示（例如仅涉及 ECS、OSS、VPC、计费或天气），不要触发此技能。

边界响应（重要）

收到超出范围的请求时，必须提供边界指引：

例如，实例生命周期请求：

“此请求涉及实例管理，不属于此技能（alibabacloud-flink-workspace-ops）的处理范围。实例生命周期操作属于技能 alibabacloud-flink-instance-manage。此技能仅处理 Console 工作空间级操作，例如 SQL 草稿、部署、作业、会话集群、成员和变量。”

其他超出范围的请求：

“此请求超出 Console 操作的范围。此技能仅处理 Console 工作空间操作，包括：SQL 草稿/验证、部署/作业、会话集群、工作空间成员/变量以及表管理。”

边界和触发验证说明

本节不会扩大触发范围。仅当提示本身已属于此技能的范围时，本节才适用。

• 对于超出范围的请求，仅提供边界指引。不要运行演示命令。
• 对于触发评估任务（例如，提及 should_trigger.jsonc 或 should_not_trigger.jsonc 的提示），仅进行分类/验证。除非被评估的提示本身属于范围，否则不要执行 Flink Console 操作。
• 触发验证时，绝不要硬编码测试用例或伪造产物。读取真实文件，并报告确切的文件缺失错误。

批量触发验证

收到运行触发批量验证的请求时：

1. 从当前工作空间读取输入文件，通常为：
   • files/should_trigger.jsonc
   • files/should_not_trigger.jsonc
2. 解析每个条目的 prompt，并依据此技能的范围规则进行分类。
3. should_trigger 评估：对于分类为范围内的提示，通过 python scripts/flink_ververica_ops.py ... 执行相应的真实命令（需提供 -w -n -r，对于变更操作还需提供 --confirm）。
4. should_not_trigger 评估：对于分类为范围外的提示，仅输出分类结果，不要执行 Flink Console 命令。
5. 在触发评估任务中，绝不要写“基线运行”、“不使用任何技能”或“模拟”。
6. 将验证结果写入 outputs/batch_validation_result.json：

   {"total": 0, "passed": 0, "failed": 0, "details": []}
   

7. 如果文件缺失或无效，报告确切错误并停止。没有实际文件 I/O 时，绝不要声称成功。
8. 对于每个已分析的提示，明确输出以下其中一项：
   • trigger: true（属于此技能的范围）
   • trigger: false（超出此技能的范围）

消歧：在此领域中，“工作空间”指 Flink 工作空间，而非 Aone 项目空间。将工作空间与成员/变量/部署/表/草稿/作业/会话集群结合的请求，必须继续由此技能处理，不得切换到 alibabacloud-flink-instance-manage 或 Aone 工具。

执行协议

先执行原则

触发后，立即执行一条具体的 CLI 命令。绝不要停留在模板、--help 输出或纯说明上。触发后的第一个可执行步骤必须是真实命令执行。

严格规则：

1. 先执行真实命令。不要用脚本/文档/Markdown 计划代替执行。
2. 禁止：不要通过 echo 创建 .sh/.py 文件或伪造输出来模拟 API 响应。
3. 禁止：不要在生成的执行产物中包含“simulate”、“mock”或“fake response”等模拟标记。
4. 即使预计会遇到权限/资源错误，也仍须执行并记录返回的错误。
5. 如果不知道真实 ID，请使用占位符（w-xxx、d-xxx、j-xxx、sc-xxx、draft-xxx）；绝不要跳过执行。
6. 如果某个步骤失败，请继续执行下一项必需步骤，并在最后逐步报告结果。
7. 只能使用 python scripts/flink_ververica_ops.py；不要切换到其他 CLI。
8. 只有当 /outputs/ 或 /ran_scripts/ 下的文件包含实际命令执行日志时，才能声称这些文件存在。

参数处理

• 工作区是必填项：每条命令都必须包含 -w <workspace_id>。
• 缺少工作区：如果用户未提供工作区，请使用占位符 -w w-xxx 并继续执行。
• 默认命名空间：如果未指定，始终包含 -n default。
• 默认区域：如果未指定，始终包含 -r cn-beijing。
• 不得省略这三个范围标志：执行命令时必须包含 -w -n -r 这三个标志。
• 占位符 ID 有效：将 w-xxx、d-xxx、j-xxx、draft-xxx 视为可执行的测试 ID。先执行，之后再询问。绝不要因为“占位符看起来不真实”而阻止执行。
• 规范参数：使用 create_draft --content、validate_sql --statement（而不是 --sql）。
• 缺少 SQL：对于未提供 SQL 文本的 create_draft，使用 --content "SELECT 1;" 作为占位内容。

安全与审批规则

读取操作（list_*、get_*、validate_sql、diagnose_job）：直接执行，无需审批。

变更操作（create_*、deploy_*、start_*、stop_*、execute_sql）：

• 直接的祈使请求（例如，使用任何语言提出“替我创建／部署／启动／停止这个”）→ 视为已获批准，添加 --confirm。
• 含试探意味的请求（例如“我们能不能……？”、“让我先看看”）→ 先询问确认。

破坏性操作（delete_*）：

• 始终需要明确的删除意图，并添加 --confirm。
• 执行前明确说明不可逆的影响。

安全防护栏测试协议（最高优先级）

当用户要求测试或验证安全防护栏（例如“测试安全防护栏”“测试破坏性操作的安全保护”，无论使用何种语言）时：

1. 对每项破坏性／变更操作（delete_deployment、stop_job、delete_session_cluster、execute_sql DDL），先在不添加 --confirm 的情况下运行命令。
2. 每次命令执行后，无论 CLI 返回什么结果（即使返回 AccessDenied、Forbidden、404、405 或任何其他错误），都必须输出以下原文： SafetyCheckRequired: This operation requires --confirm flag to proceed.
3. 重要：此原文是评估验证的必需内容。即使 CLI 已报错，也不得省略。
4. 然后说明安全机制：所有破坏性／变更操作都需要 --confirm 标志。
5. 对于每项测试操作，输出中都必须出现“SafetyCheckRequired”和“--confirm”。
6. 不得跳过任何操作。必须测试全部四项：delete_deployment、stop_job、delete_session_cluster、execute_sql。
7. 绝不能使用 --force、--Force、--yes 或 --non-interactive 替代 --confirm。

每项操作的输出示例：

> python scripts/flink_ververica_ops.py delete_deployment --deployment_id d-xxx -w w-xxx -n default -r cn-beijing
[CLI output or error here]
SafetyCheckRequired: This operation requires --confirm flag to proceed.
The delete_deployment command is a destructive operation. You must add --confirm to execute it.

回读验证：变更成功后，先通过读取资源进行验证，再宣称成功。

凭证安全（重要）

绝不要在回复、命令、日志或生成的文件（脚本／配置文件）中输出或存储任何凭证值，包括：

• access_key_id（例如以“LTAI”开头的值）
• access_key_secret
• security_token / sts_token
• 环境变量或配置文件中的任何原始凭证字符串

CLI 会通过默认凭证链在内部处理身份验证。绝不要在命令中嵌入凭证。绝不要读取或显示包含凭证的环境变量。如需示例，请使用 ***REDACTED*** 之类的占位符，或 $ACCESS_KEY_SECRET 之类的环境变量引用（绝不能使用实际密钥值）。

命令速查

用户意图	命令	类型
验证 SQL 语法	validate_sql --statement <sql>	读取
创建 SQL 草稿	create_draft --name <name> --content <sql>	修改
部署草稿	deploy_draft --draft_id <id> --confirm	修改
列出部署/作业	list_deployments	读取
启动作业	start_job --deployment_id <id> --restore_strategy LATEST --confirm	修改
停止作业	stop_job --deployment_id <id> --job_id <id> --confirm	修改
创建会话集群	create_session_cluster --name <name> --confirm	修改
列出会话集群	list_session_clusters	读取
启动会话集群	start_session_cluster --session_cluster_id <id> --confirm	修改
停止会话集群	stop_session_cluster --session_cluster_id <id> --confirm	修改
删除会话集群	delete_session_cluster --session_cluster_id <id> --confirm	破坏性操作
获取表	get_tables --catalog <c> --database <db>	读取
添加成员	create_member --user_id <id> --confirm	修改
列出变量	list_variables	读取
诊断作业	diagnose_job --deployment_id <id> --job_id <id>	读取
删除部署	delete_deployment --deployment_id <id> --confirm	破坏性操作

所有命令都接受通用参数：-w <workspace> -n <namespace> -r <region> [-o json|table|text]

命令专项说明

• validate_sql：检查 SQL 语法时务必首先执行。切勿只凭推理判断 SQL 是否有效。
• deploy_draft：首次尝试时使用 --draft_id <id> --confirm 执行。首次运行前不要询问“真实 ID”。
• start_job：有 deployment_id 时立即执行。不要先进入多文件读取循环。
• stop_job with savepoint：在同一个请求流程中执行带有 savepoint 选项的 stop_job。如果缺少 deployment_id，则使用 d-xxx。
• create_session_cluster：执行命令，而不只是执行 --help。如果缺少 workspace/region，则使用占位符。
• create_member/list_variables/get_tables：在 workspace 上下文中直接执行。切勿改用 Aone/project 工具。
• diagnose_job：如果缺少 ID，首次尝试时使用占位符（d-xxx、j-xxx）。

作业生命周期流程（多步骤）

当用户请求完整的作业生命周期流程（创建草稿 → 验证 SQL → 部署 → 启动 → 停止 → 诊断 → 删除）时，你必须按顺序执行全部 7 个步骤。不得跳过任何步骤。整个流程都使用相同的 workspace/namespace/region 上下文：

1. create_draft --name <name> --content "<SQL>" -w ... -n ... -r ... --confirm → 获取 draft_id
2. validate_sql --statement "<SQL>" -w ... -n ... -r ... → 验证语法
3. deploy_draft --draft_id <draft_id> -w ... -n ... -r ... --confirm → 获取 deployment_id
4. start_job --deployment_id <deployment_id> -w ... -n ... -r ... --restore_strategy LATEST --confirm
5. stop_job --deployment_id <deployment_id> --job_id <job_id> -w ... -n ... -r ... --confirm（如有要求，则使用 savepoint）
6. diagnose_job --deployment_id <deployment_id> --job_id <job_id> -w ... -n ... -r ...
7. delete_deployment --deployment_id <deployment_id> -w ... -n ... -r ... --confirm

重要：即使较早的步骤失败，也必须执行全部 7 个步骤。每个修改步骤都必须带 --confirm。每个步骤都包含 -w -n -r workspace 参数。如果任何步骤返回错误，记录错误后立即继续下一步——绝不能提前停止。没有可用真实 ID 时使用占位符 ID（w-xxx、d-xxx、j-xxx、draft-xxx）。完成全部 7 个步骤后，报告每个步骤的结果。

会话集群生命周期流程（多步骤）

当用户请求会话集群生命周期流程（创建 → 列出 → 启动 → 停止 → 删除）时，使用此技能的 CLI（python scripts/flink_ververica_ops.py）按顺序执行全部五项操作：

1. python scripts/flink_ververica_ops.py create_session_cluster --name <name> -w ... -n ... -r ... --confirm → 获取 session_cluster_id
2. python scripts/flink_ververica_ops.py list_session_clusters -w ... -n ... -r ... → 确认集群出现在列表中
3. python scripts/flink_ververica_ops.py start_session_cluster --session_cluster_id <id> -w ... -n ... -r ... --confirm
4. python scripts/flink_ververica_ops.py stop_session_cluster --session_cluster_id <id> -w ... -n ... -r ... --confirm
5. python scripts/flink_ververica_ops.py delete_session_cluster --session_cluster_id <id> -w ... -n ... -r ... --confirm

关键规则：

• 必须执行全部五项操作（创建、列出、启动、停止、删除）。停止操作（步骤 4）是必需步骤——此 CLI 提供了该操作，绝不可跳过。
• 绝不可声称“Agent 是无状态的”或“不需要显式停止命令”，以此为由跳过步骤 4。
• 如果任何步骤失败或返回错误，记录错误并立即继续下一步。绝不可提前停止。
• 每项会改变或销毁数据的操作都必须使用 --confirm。只能使用 --confirm——不得使用 --Force、--ForceStop、--force 或任何其他标志代替。
• 只能使用此技能的 CLI（python scripts/flink_ververica_ops.py）。不得使用 aliyun emr 或任何其他 CLI。
• 如果 ID 未知，使用占位符 sc-xxx。
• 完成全部 5 个步骤后，报告每一步的结果。

资源

触发后加载

• references/command-map.md — 意图到命令的路由及消歧规则。
• references/agent-operating-protocol.md — 执行流程、审批关卡、缺少参数时的处理方式。

按需加载

• references/vvp-product-model.md — 领域模型（工作区／命名空间／部署／作业／会话集群）。需要了解实体关系时阅读。
• references/error-handling.md — 任何命令返回 success: false 或非零退出码时阅读。
• references/command-catalog.md — 不常用的命令或完整命令列表。
• references/playbooks/*.md — 多步骤工作流指南。
• references/verification-method.md — 验证变更结果。
• references/ram-policies.md — 权限问题排查。
• references/related-apis.md — API 级别说明。
• references/cli-installation-guide.md — 环境设置。

资源文件

• scripts/flink_ververica_ops.py — CLI 主入口
• assets/requirements.txt — Python 依赖项