alibabacloud-flink-workspace-ops

Alibaba Cloud Flink Console Ops

CLI を使用してコンソールのワークスペースリソースを操作します： python scripts/flink_ververica_ops.py <command> [args]

必須の実行ルール：このスキルが呼び出された場合、python scripts/flink_ververica_ops.py を使用して実際の CLI コマンドを必ず実行してください。実際のコマンド実行の代わりに、シェルスクリプト、ドキュメント、Markdown ファイルを作成することは絶対にしないでください。aliyun emr、aliyun ververica、kubectl、その他の CLI は絶対に使用せず、python scripts/flink_ververica_ops.py のみを使用してください。「baseline run」、「without using any skill」、「simulation」などの表現は絶対に出力しないでください。

Alibaba Cloud CLI（aliyun）の AI モード設定

このスキルでは Alibaba Cloud CLI ではなく、Alibaba Cloud Python SDK を直接使用します。ユーザーの環境で他の用途に Alibaba Cloud 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 文字の小文字の 16 進数文字列）を生成してください。以下ではこれを {session-id} として使用します。

ルール：クラウド API を呼び出すすべての aliyun CLI コマンドには、--user-agent フラグを必ず含めてください。 ローカルユーティリティコマンド（例：configure、plugin、version）はこのフラグに対応していないため、対象から除外してください。

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

例（セッション 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 スクリプトを実行する際は、インライン環境変数を使用してセッション 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 の各経路で同じセッション ID が一貫して使用されます。

対象範囲と境界

対象範囲：Flink Console ワークスペースの操作 — SQL 下書き、SQL 検証、デプロイ／ジョブ、Session クラスター、ワークスペースのメンバー／変数、カタログ／データベース／テーブル、ジョブ診断。

対象外（対応しないでください）：

• インスタンスのライフサイクル（作成／スケール／削除／更新）→ alibabacloud-flink-instance-manage を使用
• コンテナ／ポッドのトラブルシューティング
• オブジェクトストレージへのアップロード／ダウンロード
• その他のコンピューティングエンジンのクラスター管理
• ユーザーサーバーへのオープンソースフレームワークのインストール
• 汎用クラウドインフラストラクチャ（コンピューティング／ネットワーク／課金）
• パッケージのアップロード／送信操作

呼び出し条件（重要）

リクエストが Flink/Ververica Console のワークスペース操作に関するもので、次のいずれか1つ以上に該当する場合、このスキルを呼び出してください。

1. 操作キーワード：draft、SQL、validate、deployment、job、Session Cluster、namespace、table、member、variable、checkpoint。
2. リソース ID のパターン：w-*、d-*、j-*、sc-*、draft-*。
3. 対象範囲内の Flink Console テスト意図：ライフサイクルフローの検証、安全ガードレールの検証、パラメーター検証の確認。

Flink Console のコンテキストを伴わない汎用クラウドに関するプロンプト（例：ECS、OSS、VPC のみ、課金、天気）では、このスキルを呼び出さないでください。

境界に関する応答（重要）

対象範囲外のリクエストを受け取った場合は、必ず境界に関する案内を返してください。

インスタンスのライフサイクルに関するリクエストの場合：

「このリクエストはインスタンス管理に関するものであり、このスキル（alibabacloud-flink-workspace-ops）の対応範囲外です。インスタンスのライフサイクル操作は、スキル alibabacloud-flink-instance-manage の対応範囲です。このスキルが対応するのは、SQL 下書き、デプロイ、ジョブ、セッションクラスター、メンバー、変数などのコンソールのワークスペースレベルの操作のみです。」

その他の対象範囲外のリクエストの場合：

「このリクエストはコンソール操作の対象範囲外です。このスキルが対応するのは、SQL 下書き／検証、デプロイ／ジョブ、セッションクラスター、ワークスペースのメンバー／変数、テーブル管理などのコンソールのワークスペース操作のみです。」

境界およびトリガー検証に関する注意事項

このセクションによってトリガーの対象範囲が広がることはありません。このスキルの対象範囲内であることがすでに確認されたプロンプトにのみ適用されます。

• 対象範囲外のリクエストには、境界に関する案内のみを返してください。デモコマンドを実行してはいけません。
• トリガー評価タスク（たとえば、should_trigger.jsonc や should_not_trigger.jsonc に言及するプロンプト）の場合は、分類／検証のみを行ってください。評価対象のプロンプト自体が対象範囲内でない限り、Flink コンソール操作を実行してはいけません。
• トリガー検証用のテストケースをハードコードしたり、成果物を捏造したりしてはいけません。実際のファイルを読み込み、ファイルが見つからない場合は正確なエラーを報告してください。

トリガーの一括検証

トリガーの一括検証を依頼された場合：

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 コンソールコマンドを実行してはいけません。
5. トリガー評価タスクでは、決して「baseline run」、「without using any skill」、「simulation」と書いてはいけません。
6. 検証結果を outputs/batch_validation_result.json に書き込みます。

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

7. ファイルが見つからない場合、または無効な場合は、正確なエラーを報告して停止してください。実際のファイル入出力なしに成功を主張してはいけません。
8. 分析したプロンプトごとに、次のいずれかを明示的に出力してください。
   • trigger: true（このスキルの対象範囲内）
   • trigger: false（このスキルの対象範囲外）

判別に関する注意：このドメインにおける「workspace」は、Flink ワークスペースを意味し、Aone プロジェクトスペースを意味しません。ワークスペースとメンバー／変数／デプロイ／テーブル／下書き／ジョブ／セッションクラスターを組み合わせたリクエストは、このスキルの対象範囲内に留め、alibabacloud-flink-instance-manage や Aone ツールに切り替えてはいけません。

実行プロトコル

まず実行する原則

トリガーされたら、具体的な CLI コマンドを直ちに実行してください。テンプレート、--help の出力、説明だけで終えてはいけません。トリガー後、最初に実行可能な手順として、実際のコマンドを実行してください。

厳守事項：

1. まず実際のコマンドを実行してください。実行の代わりに、スクリプト／ドキュメント／Markdown の計画を提示してはいけません。
2. 禁止：API 応答を模擬するために、echo や模擬出力を使って .sh／.py ファイルを作成してはいけません。
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 を含めてください。
• スコープを指定する3つのフラグを省略しない：-w -n -r の3つすべてのフラグなしでコマンドを実行しないでください。
• プレースホルダー 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. 操作を省略しないでください。次の4つをすべてテストしてください：delete_deployment、stop_job、delete_session_cluster、execute_sql。
7. --confirm の代わりに --force、--Force、--yes、--non-interactive を絶対に使用しないでください。

各操作の出力例：

> 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）を使用して、5 つの操作すべてを順番に実行します。

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

重要なルール：

• 5 つの操作（作成、一覧表示、起動、停止、削除）をすべて実行する必要があります。停止操作（ステップ 4）は必須です。この CLI に存在するため、スキップしてはいけません。
• ステップ 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 — ドメインモデル（workspace／namespace／deployment／job／session-cluster）。エンティティ間の関係を把握する必要がある場合に読みます。
• 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 の依存関係