volcengine-cli

Volcengine CLI スキル

ve を、Volcengine OpenAPI、TOS オブジェクト操作、Ark 製品のワークフロー、TLS ログサービスのワークフローに対応する統合エントリーポイントとして使用します。

エージェント呼び出し元メタデータ（必須）

エージェントが起動するすべての ve プロセスに、ヘルプやバージョンの確認、認証、API 呼び出し、再試行、ポーリング、ve tosutil／ve arkcli／ve volclog を含め、次の環境変数を渡す必要があります。

変数	必須値
VE_CALLER_TYPE	常に ai_agent を指定します。
VE_CALLER_NAME	現在のランタイム環境から、実際のエージェントホスト識別子を解決します。これはエージェントアプリケーションを識別するものであり、モデル、アカウント、ユーザー、セッションを識別するものではありません。
VE_SKILL_NAME	このコマンドを実行するワークフローで有効な Volcengine スキルのフロントマターから name を解決します。実際の volcengine-* 名を使用します。

これらの値は、ランタイムの呼び出し元情報であり、認証情報やユーザーのセットアップ手順ではないため、ご自身で設定してください。 固定値は VE_CALLER_TYPE=ai_agent のみです。実行のたびに、現在のホストと有効なスキルの両方を解決してください。どちらにもハードコードされたデフォルト値はありません。たとえば、現在のエージェントが Codex の場合に限り codex が有効であり、現在の操作をそのスキルが担う場合に限り volcengine-cli が有効です。エージェント環境または有効なスキルが変わった場合は、値を再度解決してください。共有ヘルパーと上流製品の CLI には、実際に呼び出しを行う Volcengine スキルの識別情報が引き継がれます。実行ファイル名やインストールディレクトリによって識別情報が決まることはありません。

ツールのプロセス環境、またはコマンド単位の代入によって、実行のたびに3つすべての値を渡してください。新しいツール呼び出しでは新しいシェルが起動する場合があるため、以前の export だけでは不十分です。複数のコマンドを含むシェルブロックでは、ブロックの先頭で3つすべてをエクスポートし、ワークフローを切り替える前にスキル名を更新してください。代入は実行ファイルの前に置いてください。これらは CLI フラグ、API パラメーター、リクエスト本文に追加するフィールドではありません。このプレフィックスには、VOLCENGINE_SAFETY_* 変数を絶対に追加しないでください（§2）。 パイプラインや $(...) では、ve プロセス自体に変数を設定するか、パイプラインの実行またはコマンド置換の展開前に、同じシェルで変数をエクスポートしてください。

コマンドの形式 — エージェントは、実行前に両方のプレースホルダーを、実際のランタイム環境と有効なスキルから解決した値に置き換える必要があります。

VE_CALLER_TYPE=ai_agent \
VE_CALLER_NAME="<agent-id>" \
VE_SKILL_NAME="<current-volcengine-skill>" \
  ve ecs DescribeInstances --output json

install_ve.sh、ve_login_remote.sh、audit_extend_apis.py、call_extend_api.py など、ve を起動するすべてのスクリプトにも同じ環境を適用してください。デタッチされたログインプロセスを含め、子プロセスにはこの環境が引き継がれます。後続のヘルパー呼び出しでも、改めて環境を渡す必要があります。ダウンロードしたインストーラーをパイプ経由で実行する場合は、ダウンロードコマンドだけでなく、インストーラーを実行するシェルに環境を設定してください。必要な認証・設定値と子 CLI の引数はそのまま維持し、呼び出し元メタデータについては、以下の Ark 委譲ルールに従ってください。

このスキルおよび参照先の他の箇所にあるコマンド例はコマンド構文を示しています。ここに記載した環境要件は、それらの例を実行する場合にも適用されます。

Ark の委譲：呼び出し元変数は1組のみ

ve arkcli ... では、上記の VE_* 呼び出し元変数3つを渡してください。ve がそれらを Ark CLI の環境変数に変換するため、エージェントは ARKCLI_CALLER_TYPE、ARKCLI_CALLER_NAME、ARKCLI_SKILL_NAME も追加してはいけません。単独の Ark の例にある ARKCLI_NO_UPDATE_NOTIFIER=1 も、コマンドのプレフィックスにコピーしないでください。委譲先のプロセスは ve に管理させます。このルールは、Ark の認証、モデル操作、ヘルプ、バージョンの各コマンドに適用されます。

VE_CALLER_TYPE=ai_agent \
VE_CALLER_NAME="<agent-id>" \
VE_SKILL_NAME="<current-volcengine-skill>" \
  ve arkcli auth status

実際のエージェント環境と有効な Volcengine スキルからプレースホルダーを解決してください。単独の Ark 呼び出しで使用したプロセス環境を再利用する場合、この呼び出しでは、上記のラッパーが管理する4つの変数を除外してください。その他の製品設定と認証情報は維持してください。単独の arkcli ... 呼び出しでは、引き続き上流の Ark スキルの環境ルールに従います。

製品 CLI のルーティング

バージョン要件： §0 の最小バージョン（ve >= 1.1.11）は、ve tosutil、ve arkcli、ve volclog など、別の CLI への委譲にも適用されます。委譲する前に確認してください。--help にプロキシコマンドが表示されるだけでは、この要件を満たしません。

ve が利用できる場合、単独の tosutil、arkcli、volclog もインストールされている場合でも、ve tosutil、ve arkcli、ve volclog を優先してください。TOS コマンドの表記は tosutil です。toscli は互換性のためのエイリアスです。既存の TOS スキルの名前は volcengine-tosutil（volcengine-tosutils ではありません）です。

タスク	エントリーポイント	使用前に読むもの
クラウドリソース全般の OpenAPI	ve <service> <Action>	§§1–5 のネイティブ API ワークフロー
TOS バケット、オブジェクト、転送	ve tosutil <command>	volcengine-find-skills を使用して volcengine-tosutil を検索し、見つからない場合はインストールして、その手順を読む
Ark モデル、推論、生成、エンドポイント、ファインチューニング、プラン、使用状況	ve arkcli <command>	以下の手順に従い、該当する 公式 Ark スキル をダウンロードして読む
TLS（ログサービス）のログ検索、分析、取り込み、エクスポート、Project/Topic、LogCollector による収集	ve volclog <command>	volcengine-find-skills を使用して volcengine-tls（収集の場合は volcengine-tls-logcollector）を検索し、見つからない場合はインストールして、その手順を読む

TOS については、ファインダーの list → 正確な volcengine-tosutil を選択 → 見つからない場合はインストール → インストールを確認、のフローに従ってください。実行前に、インストールしたスキルと、そのスキルが選択したリファレンスを読み込んでください。ネイティブな tosutil コマンドの例を使用し、tosutil ... を ve tosutil ... に置き換えてください。

TLS については、正確な volcengine-tls、または LogCollector による収集の場合は volcengine-tls-logcollector を指定して、同じファインダーフローに従ってください。これらのスキルにはネイティブな volclog ... の例が記載されています。ve volclog ... として実行してください。ve にはネイティブな tls OpenAPI コマンドがありません。ve volclog が不明なサービスを報告したり、--force を提案したりする場合、使用中の ve は上記のバージョン要件を満たしていないため、--force を追加するのではなく ve をアップグレードしてください。

Ark については、上記の公式リポジトリからタスクに合ったスキルを選び、arkcli-shared と、その手順で必要とされる依存関係とともにインストールしてください。これらの上流の arkcli-* 名は、ローカルの Volcengine ファインダーカタログには含まれていません。Ark リポジトリから直接インストールしてください。たとえば、Codex でモデルを検索する場合は次のようにします。

npx --yes skills add https://github.com/volcengine/ark-cli \
  --skill arkcli-shared arkcli-auth arkcli-models --agent codex --yes --copy --full-depth
npx --yes skills list --agent codex --json

実際のホストに合った --agent とタスクスキル名を使用してください。既定ではプロジェクト単位でインストールされます。ユーザーレベルでインストールする場合に限り、両方のコマンドに --global を追加してください。実行前に、名前を確認し、インストールした arkcli-shared/SKILL.md、タスクスキル、およびそのスキルが選択したリファレンスを読んでください。ホストが新しくインストールしたスキルを読み込めない場合は、ファインダーの指示に従い、元のタスクと完了済みのコンテキストを引き継いで新しい会話を開始してください。製品に関する手順は各スキルに従ってください。このスキルは、それらのスキルへの案内のみを行います。

arkcli、tosutil、volclog は、透過的に委譲される CLI です。例では実行ファイルのプレフィックスのみを置き換え、それ以降の引数はすべてそのままにしてください。認証、プロファイル、パラメーター、出力、終了コードは各 CLI 固有のものが引き継がれます。--output、--query、--force、--detail、PascalCase パラメーター、--DryRun などのネイティブ API の規則は適用されません。ローカルの安全ポリシーと、その --yes による再試行（§2）も適用されません。製品スキル独自の確認ルールに従ってください。

• 対応している子フラグは、子コマンドの後に指定してください。ve --profile <name> arkcli ... は無効です。 ve arkcli ... --profile <name> は ve のプロファイルではなく、Ark のプロファイルを選択します。
• 製品のスキルに従って、認証、フラグ、出力の処理を行ってください。子コマンドの引数はすべてそのままにして、tosutil ... / arkcli ... / volclog ... を ve tosutil ... / ve arkcli ... / ve volclog ... に置き換えてください。 ve arkcli では、Ark の委任 の説明にある VE_* 呼び出し元メタデータのみを使用してください。単体の Ark 用呼び出し元／通知プレフィックスはコピーしないでください。必要な製品環境変数の設定は ve の前に置いてください。
• ve sts GetCallerIdentity が動作しても、いずれかの子コマンドが認証済みであることの証明にはなりません。選択した製品のスキルに従ってください。ヘルプ、バージョン、ローカルプレビューのタスクでは、ネイティブ API ログインは不要です。
• ve は委任の前に、現在の Console Login セッションを更新することがあります。ただし、その更新によってすべての ve 認証情報やプロファイル設定が子コマンドの設定に反映されるわけではありません。更新に関する警告だけでは、子コマンドが失敗したとは判断できません。

製品 CLI のインストールとアップグレード

ve はまず PATH から子コマンドを探し、次に管理対象ディレクトリを確認します。子コマンドが見つからない場合は、初回使用時に公式 CDN からチェックサムを検証してインストールします。製品を別途インストールする必要はありません。タスクに必要な子コマンドだけを確認してください：

ve tosutil version
ve tosutil help
ve arkcli --version
ve arkcli --help
ve volclog --version
ve volclog --help

管理対象の子コマンドは、ve proxycli upgrade tosutil、ve proxycli upgrade arkcli、または ve proxycli upgrade tls-cli でアップグレードできます。管理コマンドでは製品 ID（TLS の場合は tls-cli）を指定し、実行時にはネイティブのコマンド名（ve volclog）を使用します。 これらのコマンドは、PATH 上の外部インストールには手を加えず、元のパッケージマネージャーに委ねます。ve だけをアップグレードしても、外部インストールはアップグレードされません。子コマンドが ve --help に表示されない場合は、まず ve をアップグレードしてください。製品フラグと利用可能な機能は、解決された子コマンドのヘルプに従います。

---

0. ve CLI のインストールまたはアップグレード

常に最新リリースを実行してください。このスキルでは、現行の ve（デバイスコード方式の ve login、--output／--query、--force、--detail、二重ダッシュ形式のシステムフラグ）を前提としています。古いビルドへのサポート経路はありません。代わりにアップグレードしてください。

最低バージョン（必須）： タスクで最初の他の ve コマンド（ネイティブ OpenAPI 呼び出し、ログイン、製品 CLI への委任を含む）を実行する前に、ve version を実行し、ve >= 1.1.11（安定版リリースの 1.1.11 以降）であることを確認してください。ve が見つからない、1.1.11 より古い、またはバージョンを確認できない場合は、以下のいずれかの方法でインストールまたはアップグレードし、続行する前にもう一度 ve version を実行してください。npm が引き続き古いバージョンをインストールする場合は、設定されている npm ミラーの更新が遅れている可能性があります。その場合は CDN インストーラーまたは GitHub Releases を使用してください。

オプション 1：npm（推奨）

npm i -g @volcengine/cli

オプション 2：CDN インストーラー（Node.js がない場合、または npm に接続できない場合）

curl -fsSL https://cloudcache.volccdn.com/ve/install.sh | sh
# or
wget -qO- https://cloudcache.volccdn.com/ve/install.sh | sh

同じスクリプトが scripts/install_ve.sh として同梱されています。CDN から最新バージョンを取得し、ホストの OS／CPU に対応するアーカイブをダウンロードして、公開されている SHA256SUMS と照合して検証します。書き込み可能な場合は /usr/local/bin にインストールし、それ以外の場合は ~/.local/bin にインストールします（sudo は使用しません）。macOS の隔離フラグを解除し、ve skills update を実行します。--version <ver>、--install-dir <dir>、--dry-run、および VE_VERSION／VE_INSTALL_DIR／VOLCENGINE_CLI_DOWNLOAD_BASE_URL／VOLCENGINE_CLI_SKIP_SKILLS 変数については、スクリプトのヘッダーに記載されています。Windows の場合は、npm またはリリースページを使用してください。

オプション 3：GitHub Releases — https://github.com/volcengine/volcengine-cli/releases

ネイティブ OpenAPI 機能の確認： ve login --help に --no-browser が表示され、ve ecs DescribeInstances --help の System Flags に --output が表示される必要があります。どちらかが表示されない場合は、npm i -g @volcengine/cli@latest でアップグレードするか、CDN インストーラーを再実行してから続行してください。これらの確認は、上記の最低バージョン要件の代わりにはなりません。

---

1. ネイティブ OpenAPI の初期化（API 呼び出し用）

このセクションは、ve <service> <Action> と拡張ヘルパーに適用されます。委任された製品コマンドについては、まず 製品 CLI のルーティングに従い、選択した製品スキルを使用してください。

CLI システムフラグ

すべての ve <service> <Action> 呼び出しでは、Action の後に次のフラグを指定できます。いずれもハイフンは 2 つです。

フラグ	目的
--profile <name>	この呼び出しに限り、設定済みのプロファイルを使用します
--region <region>	この呼び出しに限り、リージョンを上書きします
--endpoint <host>	この呼び出しに限り、エンドポイントを上書きします
--lang EN|ZH	この呼び出しの表示言語
--version <YYYY-MM-DD>	API バージョン。省略時はメタデータのデフォルトを使用します（--force と併用する場合は必須）
--method GET|POST	HTTP メソッド。メタデータのデフォルトがあればそれを使用し、なければ GET を使用します
--force	メタデータの検証（§3）をスキップします。値は不要です。--force true のようには指定しないでください
--output <fmt> / --query <jmespath>	応答のフォーマットと射影（§4）
--header Name=Value、--body '{...}'	カスタムヘッダー／生の JSON ボディ

API パラメーターはパスカルケース（--Region、--InstanceIds.1）、システムフラグは小文字（--region）なので、通常は名前が衝突しません。API パラメーターの名前が小文字のシステムフラグと完全に一致する場合（独自の --query または --lang フィールドを持つ API の場合）に限り、システムフラグを 3 つのハイフンで記述し（---query）、API パラメーターは 2 つのハイフンのままにしてください。それ以外の場所では、ハイフン 3 つのフラグを使用しないでください。

CLI 管理コマンド（ve configure ...、ve login、ve sso login）とヘルパースクリプトでは、--help に表示されるとおり、それぞれ独自のハイフン 2 つのフラグを使用します。

プロファイルの選択（会話中は固定）

ve はプロファイルを通じて異なる認証情報を使用できますが、エージェントが独自にプロファイルを選択してはいけません。

• ユーザーがプロファイルを明示的に選択していない場合は、CLI のデフォルト解決を使用します。ve sts GetCallerIdentity を直接実行してください。最初にすべてのプロファイルを一覧表示して、自分で選択してはいけません。
• ユーザーがプロファイルを明示的に選択した場合は、この会話での後続のすべてのコマンドでも同じプロファイルを使い続けます：ve ecs DescribeInstances --profile prod、python3 scripts/call_extend_api.py --profile prod ...。
• プロファイル名、リージョン、一覧の順序、最近の利用状況、成功率、タスクの内容から、希望するプロファイルを推測してはいけません。
• デフォルトの ID がタスクのリスクに適合しない場合、またはプロファイルの選択が必要な場合は、現在のデフォルト ID をユーザーに伝え、候補のプロファイル名のみを一覧表示して、ユーザーの選択を待ってください。
• この会話でプロファイルが固定された後は、ユーザーから明示的に切り替えを求められない限り、別のプロファイルに切り替えてはいけません。

認証情報が使用可能であることを確認するため、ID 確認コマンドを実行してください：

ve sts GetCallerIdentity

成功 — 現在のアカウント ID とリージョンをユーザーに伝えてから、タスクを進めてください。

後からリージョンを切り替える場合：サービス API 呼び出しで --region を指定すると、その呼び出しに限ってリージョンが上書きされます（応答の Region もそれに応じて変わります）。また、プロファイルにデフォルトのリージョンが設定されていない場合は、VOLCENGINE_REGION がデフォルトになります。変わらないのは、プロファイルに紐付けられたログインセッション／アカウントです。リージョンの上書きはリクエストの送信先を変えるだけで、ユーザーの ID は変わりません。独自にリージョンやプロファイルを切り替えてはいけません。ユーザーから明示的に求められた場合に限り、--region を指定するか、プロファイルを切り替えてください（ve configure profile --profile <name>）。ve configure list は候補のプロファイル名を表示する場合にのみ使用してください。一覧表示後、自分でプロファイルを選んではいけません。これは ve login 自体に指定する --region フラグとは別です。こちらは必須です（下記を参照）。

失敗 — 使用可能なプロファイルがありません。デフォルトの手順は ve login（コンソールログイン）です。最初にこの手順をユーザーに伝え、「AK/SK を使う」「STS トークンを使う」「SSO を使う」と伝えれば切り替えられることも案内してください。

以前は使用できていたセッションがタスクの途中で期限切れになった場合も、同じ手順を適用します。どのスキルがコマンドを発行したかにかかわらず、ve コマンドで failed to refresh session token. Please run 've login' to re-authenticate（または類似のトークン更新／セッション期限切れメッセージ）が発生した場合は、これと同じ失敗です。エラー文はユーザーに ve login の実行を求めていますが、その指示をユーザーに伝えたり、ユーザー自身のターミナルで実行するよう求めたりしてはいけません。以下のコンソールログイン手順を自分で実行し、サインインリンクのみをユーザーに渡してください。再ログインの対象は、使用中だったプロファイルでなければなりません。会話の前半でプロファイルが固定されている場合は、start にそのプロファイルを渡し、ログインとその検証の両方が同じプロファイルを対象とするようにしてください。プロファイルを省略すると default が更新され、固定されたプロファイルは使用できないままになり、デフォルトのアカウントコンテキストが汚染されます。

デフォルト：scripts/ve_login_remote.sh を使ったコンソールログイン

ve login を直接呼び出してはいけません。必ず scripts/ve_login_remote.sh を使用してください。 ve login はデバイスコードフローです。ve が認証用 URL とユーザーコードを表示し、ユーザーが任意のデバイスのブラウザーで承認するまでポーリングします。デバイスコードはその ve プロセス内にしか存在しないため、このヘルパーはプロセスを切り離し（setsid）、ツール呼び出しの境界を越えても処理が続くようにし、URL とコードを記録して、ve のプロンプトに応答し、結果を検証します。自分で ve login を呼び出すと、プロセスが孤立して接続が切れます。

会話で最初に start を実行する前に、references/console-login.md を最後まで読んでください。手順、すべての終了コード、start-wait のバリエーション、調整方法、フローを妨げる要因の完全な一覧が記載されています。概要は次のとおりです。

scripts/ve_login_remote.sh start <region> [profile]   # prints URL= CODE= LINK= EXPIRES_IN= NEXT=
scripts/ve_login_remote.sh url                        # same block, never blocks (11 = not yet, 3 = process gone)
# hand the user LINK (fallback: URL + CODE), end the turn, wait for "done"
scripts/ve_login_remote.sh verify [profile]           # 0 ok · 11 still pending · 13 logged in but API unreachable · 10 start over
scripts/ve_login_remote.sh abort                      # on user interrupt / expired code, then start again

リージョン：ユーザーが指定したリージョン、指定がなければ VOLCENGINE_REGION、それもなければ cn-beijing です。ユーザーが以前にプロファイルを固定した場合に限り [profile] を渡し、start と verify の両方に同じ値を渡してください。

リファレンスを読んでいなくても、次の条件は必ず守ってください。

• 実行計画と代替方法（「AK/SK を使う」と言えば切り替えられること）を伝えてから開始してください。ログイン方法のメニューを提示してはいけません。
• start がハングまたは強制終了しても、何も証明されません。結論を出す前に url／status を呼び出してください。その場合でも、start や abort を再試行したり、nohup に切り替えたりしてはいけません。
• ユーザーから貼り戻されるものは何もありません。認証コードもありません。承認したとユーザーが伝えたら verify を実行してください。
• verify の終了コード 13 は、ログインが成功したものの、ホストが open.volcengineapi.com に接続できないことを意味します。ログインを再開してはいけません。
• 表示されたとおりの LINK を使用してください。signin.volcengine.com の URL を組み立てたり、以前のプロセスで使った URL を再利用したりしてはいけません。
• start の終了コード 4 は、ve が見つからないか、デバイスコードログインに対応するバージョンより古いことを意味します。§0 に従ってインストールまたはアップグレードしてから、再試行してください。

ve login が失敗した場合（ネットワークエラー、start の終了コード 4、どのデバイスにもブラウザーがない場合）、またはユーザーが別の方法を求めた場合は、以下の代替方法に切り替えてください。

代替方法：AK/SK（長期認証情報。CI/CD またはスクリプト向け）

ユーザーに AccessKey と SecretKey を尋ねてから、次を実行してください。

ve configure set --profile default --region cn-beijing \
  --endpoint open.volcengineapi.com \
  --access-key <AK> --secret-key <SK>

STS（短期）認証情報の場合は、--session-token <TOKEN> も渡してください。

現在のシェルだけで使う場合の代替方法：VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY、VOLCENGINE_REGION をエクスポートし、必要に応じて VOLCENGINE_SESSION_TOKEN もエクスポートしてください。

代替方法：SSO／Cloud Identity Center（エンタープライズフェデレーション向け）

3 段階でセットアップします。最初に SSO の開始 URL とセッション名をユーザーに尋ねてください。

ve configure sso-session --name <session-name> \
  --start-url https://<sso-host>/userportal \
  --region cn-beijing \
  --registration-scopes cloudidentity:account:access,offline_access

ve configure sso --profile <profile-name> --sso-session <session-name>

ve configure profile --profile <profile-name>

次に ve sso login --sso-session <session-name> を実行してください（ヘッドレスマシンでは --no-browser を使用します）。

認証情報の安全性

• ~/.volcengine/config.json を読み取ってはいけません。 AK/SK とセッショントークンが含まれています。
• --secret-key を指定して ve configure set を実行する場合は、Claude 経由で実行するのではなく、ユーザー自身のシェルにコマンドを貼り付けて実行してもらう方法を優先してください。コマンドライン引数として渡されたシークレットは、シェルの履歴やプロセス一覧に残るためです。
• AK/SK、シークレットキー、セッショントークンをプレーンテキストでユーザーに表示してはいけません。

---

2. 安全ルール（必須）

以下はすべての会話に適用されます。

1. デフォルトは読み取り専用 — ユーザーから変更を明示的に依頼されない限り、読み取り専用モードで実行します
2. 認証情報を保護する — ~/.volcengine/config.json は読み取らないでください。また、アクセスキー、シークレットキー、セッショントークンを出力に含めないでください
3. 安全ポリシーには手を加えない — ユーザーからポリシー自体の変更を明示的に依頼されない限り、ve configure safety-policy enable|disable|add|remove を実行せず、~/.volcengine/safety-policy.json を読み取ったり編集したりせず、コマンドのプレフィックス、スクリプト、環境内で VOLCENGINE_SAFETY_POLICY_ENABLED、VOLCENGINE_SAFETY_POLICY_RULES、VOLCENGINE_SAFETY_SKIP_CONFIRM を設定、解除、または上書きしないでください。

操作の実行または再試行の承認は、安全ポリシーの変更を許可するものではありません。ポリシーを変更するには、ポリシー自体の変更を明示的に依頼する必要があります。

ネイティブの OpenAPI 呼び出しでは、確認元を必ず 1 つだけ使用してください。安全ポリシーが有効で、ルールが空でない場合は CLI を使用し、それ以外の場合はこのスキルに組み込まれたルールを使用します。同じ操作に両方を適用してはいけません。

確認モードを選択する

会話で最初のネイティブ ve <service> <Action> 呼び出しを行う前に（ve sts GetCallerIdentity を含む）、後続の呼び出しと同じ呼び出し元メタデータおよび環境を使用して、次を実行します。

ve configure safety-policy show

終了コードではなく、標準出力とメッセージ本文から判断します。安全ポリシーに対応していない ve には safety-policy コマンドがありません。標準出力には何も出さず、標準エラーに ve configure の使い方を表示し、終了コード 0 を返します。

出力	モード
標準出力が "enabled": true かつ空でない rules リストを含む JSON	安全ポリシー — CLI に適用させます。スキルに組み込まれた確認ルールは適用しないでください
標準出力が "enabled": false または空の rules リストを含む JSON	組み込みルール — 組み込みルール のみを適用します
出力に load effective safety policy: が含まれる	いずれでもありません。ポリシーが修正されるまで ve はすべての API 呼び出しを拒否します。エラーをユーザーに報告し、停止してください
その他の場合：標準出力が空、ve configure の使い方、不明なコマンドのエラー、その他の非 JSON 出力（終了コードは問いません）	組み込みルール — ve は安全ポリシーに対応していません

モードの選択には、enabled と rules が空かどうかのみを読み取ってください。操作を実行できるかどうかを判断するために、個々のポリシールールを解釈、照合、またはキャッシュしてはいけません。その判断は CLI が行います。

会話中は選択したモードを維持します。ユーザーがポリシーが変更されたと伝えた場合、または組み込みモードでの呼び出しがブロックされたり確認を求められたりした場合にのみ、再度 show を実行します。その後、新しい出力で選択されたモードを続けて使用します。

組み込みルール

組み込みモードでのネイティブ呼び出しにのみ適用します。拡張ヘルパーの呼び出しには、引き続きこの組み込みの確認ルールを適用します。

レベル	操作の種類	動作
読み取り専用	Describe* / List* / Get* / Query*	直接実行します。確認は不要です
書き込み	Create* / Run* / Allocate* / Attach* / Associate* / Authorize*	コマンド全体を表示し、ユーザーの確認を待ちます
破壊的	Delete* / Terminate* / Release* / Revoke* / Modify* / Stop* / Detach*	コマンドと影響の概要を表示し、ユーザーの確認を必須とします

1. まず DryRun — 書き込みまたは破壊的な操作が --DryRun true に対応している場合は、計画を確認するために DryRun を実行してから、実行前に確認を求めます
2. 実行前に確認 — 書き込み操作ではコマンド全体を表示し、承認を待ちます

リファレンスにある「最初にユーザーに確認する」「明示的な確認を必須とする」という確認に関する記述は、これらのルールに従います。

ローカル安全ポリシー

安全ポリシーモードでネイティブ呼び出しを行う場合、上記の組み込みルールやリファレンスの確認に関する注記は適用しないでください。ve は --force を使った呼び出しを含むすべてのネイティブ呼び出しをチェックするため、タスクに必要なコマンドを実行し、CLI の結果に従ってください。

ve の結果	ポリシーの判断	対応
API レスポンスまたは API エラー	安全ポリシーによるブロックなし	通常の API 結果またはエラーに対処し、確認手順を追加しないでください。
operation blocked by safety policy: <service> <Action> (rule: <pattern>) / 操作被安全策略拒绝：...	deny。リクエストは送信されていません	操作が拒否され、現在のポリシーでは続行できないことをユーザーに伝えてください。ポリシーを調整するか尋ね、そのターンを終了して返答を待ってください。再試行したり、自分の判断でポリシーを変更したりしないでください。
safety policy requires confirmation for: <service> <Action> / 安全策略要求确认以下操作：...	confirm。リクエストは送信されていません	対象と影響を簡潔に説明し、続行するか尋ねてから、そのターンを終了してください。新たに明示的な承認を得た後、--yes を追加して同一のコマンドを一度だけ再実行してください。呼び出しが失敗した場合でも、承認は使用済みとなります。

• すべての操作は --yes（または -y）を付けずに開始し、ユーザーの承認を得た後の一度だけの再試行に限り追加してください。同じコマンドに対するものも含め、会話の以前のターンで得た承認は無効です。
• ve が Type 'yes' to proceed / 输入 'yes' 继续 で待機している場合、応答したり、入力を ve にパイプしたりしないでください。その他のメッセージについては、references/common-errors.md を参照してください。
• 書き込みまたは破壊的な操作は、ツール呼び出しごとに 1 つだけ実行し、次の操作に進む前に結果を確認してください。複数コマンドを含むシェルブロック内のコマンドがブロックされても、その後のコマンドは停止しません。読み取りも確認のために保留されることがあります。呼び出しが横取りされた場合は、ポーリングループを停止してください。
• 複数の操作で確認が必要な場合は、それぞれを --yes なしで一度実行し、横取りされたコマンドをすべてユーザーに列挙してください。ユーザーが明示的に承認したコマンドのみ、--yes を付けてそれぞれ一度だけ再試行してください。
• 拒否または保留された操作を、別の方法で実行しないでください。サービスの別の表記やバージョン、--force、Cloud Control、拡張機能ヘルパー、製品 CLI、SDK、または生の HTTP を使用してはいけません。ve はサービスのすべての表記にルールを適用します（rds_mysql、rdsmysql、rdsmysqlv2、および cloudtrail、cloudtrail20180101）。
• このポリシーは委任された製品 CLI（ve tosutil、ve arkcli、ve volclog）には適用されません。それぞれの製品スキルに従ってください。

DryRun に関する注意

DryRun の検証が成功すると、stderr に DryRunOperation が出力され、終了コード 1（ゼロ以外）が返されます。これは想定された動作です。

output=$(ve <svc> <action> --DryRun true ... 2>&1)
if echo "$output" | grep -q "DryRunOperation"; then
  echo "Parameter validation passed"
fi

---

3. API の特定とパラメーターの取得

API の特定（サービス名と Action 名を見つける）

Step 1: Service name + Action known? -> Use them directly; skip to "Retrieve parameters"
Step 2: Service name known, Action unknown?
  -> ve <service> 2>&1 | grep -i <keyword>
Step 3: Service name also unknown?
  -> ve 2>&1 | grep -i <service keyword>
Step 4: None of the above work?
  -> python3 scripts/find_api.py <keyword>   (returns Service, Action, Version)

パラメーターの取得（Action が判明した後）

--help は簡潔な情報（名前、型、必須／任意）を表示します。--help --detail では、各パラメーターの詳細な説明、列挙値、制約、例が追加されます。CLI 自身に含まれる API ドキュメントのため、外部から取得する必要はありません。

状況	コマンド
読み取り専用（Describe/List/Get）	ve <svc> <Action> --help — 通常は名前だけで十分です
書き込み／破壊的操作（Create/Run/Delete…）	ve <svc> <Action> --help --detail — 必須フィールド、ネストされた構造、例を確認します
--help の後も不明点がある	--help --detail を実行し、中国語のテキストを表示するには --lang ZH を追加します
Invalid* / Missing* のようなエラー	--help --detail で名前、必須フィールド、範囲を再確認します

ve ecs DescribeInstances --help
ve ecs RunInstances --help --detail
ve ecs RunInstances -h --detail --lang ZH

同じ出力の Parameter Form / --body セクションで、そのアクションがフラットなパラメーターを取るのか、JSON ボディを取るのかを確認できます（§4）。

複数のアクションの比較、エラーコードの意味、ページネーションの動作、バッチ版の有無など、1 つのアクションのパラメーターを超える API に関する質問には、API Explorer に直接問い合わせる volcengine-api スキルを読み込んでください。

ve コマンド名と API バージョンの関係

• デフォルトバージョン -> ve コマンド = サービスの基本名（例：iam）
• デフォルト以外のバージョン -> ve コマンド = サービス名 + ハイフンを除いたバージョン（例：iam v2021-08-01 -> iam20210801）
• 判断に迷った場合：ve 2>&1 | grep <service> で確認します

CLI メタデータに記載されていない API の呼び出し：--force

ve が unknown service "<svc>" または unknown action と応答する場合でも、その API が存在する（ユーザーから提供された、find_api.py が Service／Action／Version を見つけた、またはドキュメントに記載されている）なら、--force を付けて呼び出します。--force はローカルのメタデータチェックをスキップするため、メタデータに含まれる情報をあなたが指定する必要があります。つまり、バージョンと、CLI が認識していないサービスの場合はエンドポイントです。

ve newservice DescribeNewResource \
  --version 2024-01-01 \
  --endpoint open.volcengineapi.com \
  --SomeParam value \
  --force

• --version は必須です（--force の使用時は --version が必要です）。未知のサービスでは、プロファイルまたは VOLCENGINE_ENDPOINT でエンドポイントがすでに設定されていない限り、--endpoint も必須です。
• POST API では --method POST を指定します（デフォルトは GET）。JSON ボディには --body '{...}' を指定します（--Param の値と併用できません）。サービスが固定リージョンで署名する場合は --region を指定します。
• --force は存在を示すフラグです。--force を指定し、--force true とはしません。
• パラメーターは検証されません。ユーザーの資料、volcengine-api スキル、または references/extend-apis.md から取得してください。決して推測しないでください。find_api.py が見つけるのは Service／Action／Version のみで、パラメーター、メソッド、エンドポイントは返しません。
• §2 は、リストに記載されたアクションとまったく同様に適用されます。ローカルの安全ポリシーは --force を使った呼び出しにも適用されます。
• TLS（日志服务）には --force を使用しないでください。ve には tls OpenAPI コマンドがないため、Product CLI ルーティングテーブルを通じて TLS タスクを ve volclog に振り分けてください。

references/extend-apis.md には、以前ヘルパースクリプトでラップされていた拡張サービス（CDN、DCDN、domain、Flink、GA、IoT、Live、MCDN、Metrics、sec_agent、trademark、VEEN、VKE）のサービスコード／バージョン／エンドポイント／署名リージョンの設定方法が記載されています。

拡張ヘルパー（1 回のリクエストでクエリとボディを併用する場合のみ）

ve --force では、1 回の POST で URL クエリパラメーターとリクエストボディを同時に送信できません。一部の API（VMP Prometheus クエリ、Flink GWS）ではこれが必要です。その場合に限り、ヘルパーを使用してください。

python3 scripts/call_extend_api.py --list
python3 scripts/call_extend_api.py --api QueryMetrics --params '{"workspace":"<id>","query":"up"}'

ve のアップグレード後、python3 scripts/audit_extend_apis.py を実行してください。新しいメタデータでネイティブに対応できるレシピ／ヘルパーのエントリーが一覧表示されるため、削除できます。

同じ形式の未登録 API 向けに、フリーモード（--service/--version/--query-keys）もあります。認証情報、オプション、登録済みリストについては references/extend-apis.md を参照してください。この会話でユーザーが明示的にプロファイルを選択していない限り、--profile を渡さないでください。

拡張ヘルパーにも組み込みの確認ルール（§2）が適用されます。これらはネイティブ CLI の安全ポリシー統合の対象外です。

---

4. API 呼び出しの実行

基本形式

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME=<agent-id> VE_SKILL_NAME=<current-volcengine-skill> \
  ve <ServiceCode> <ActionName> --ParamName "value" [system flags]

システムフラグ（--profile、--region、--endpoint、--output、--query、…）は Action の後に指定し、パラメーターとの相対的な順序は任意です。

パラメーターの渡し方

形式は --help の出力から判断します。

• フラットなパラメーター形式：--help に個別の --Key type エントリーが表示される場合（例：ECS、VPC、IAM）-> --Key "value" で渡します。
• 配列パラメーター：--help に表示される番号付き CLI 形式（--InstanceIds.1 "$instance_id" や --SubnetIds.1 "$subnet_id" など）を優先してください。すべてのアクションで JSON 配列文字列が受け付けられるとは限りません。
• JSON 形式：--help に --body '{...}' のみが表示される場合（例：Redis、CR、その他の POST API）-> --body '{...}' で渡します。

# Flat parameters — nested fields use dot notation; arrays use .N index (starting from 1)
ve ecs RunInstances --ZoneId "cn-beijing-a"
ve ecs RunInstances --NetworkInterfaces.1.SubnetId "subnet-xxxx"
ve ecs RunInstances --Tags.1.Key "publish-by" --Tags.1.Value "deploy-skill"

# JSON format (when --help only shows --body)
ve redis CreateDBInstance --body '{"InstanceName":"demo","RegionId":"cn-beijing","ConfigureNodes":[{"AZ":"cn-beijing-a"}],"ShardedCluster":0,"NodeNumber":2,"ShardCapacity":1024,"ShardNumber":1,"EngineVersion":"6.0","SubnetId":"subnet-xxxx","VpcId":"vpc-xxxx","Password":"<secret>","Tags":[{"Key":"publish-by","Value":"deploy-skill"}]}'

出力形式とクエリ

すべての API 呼び出しで --output と --query を使用でき、JSON に対する場当たり的な grep／jq の代わりになります。

--output	用途
json（デフォルト）	完全なレスポンス。プログラムで解析する形式です
table／table-num	人間が読みやすい一覧。table-num では行番号の列が追加されます。リソース一覧をユーザーに表示するのに適しています
text	1 行につき 1 つのプレーンな値。シェル変数への単一フィールドや ID 一覧の格納に適しています
yaml	人間が読みやすいネストされた詳細情報
off	呼び出しを実行しますが、何も出力しません（レスポンスに依存する --query の評価をスキップします）。レスポンスが本当に不要な呼び出しに限ってください。新しいリソース ID がレスポンスにしか含まれないため、Create*／Run*／Allocate* では使用しないでください

--query では、整形前に完全なレスポンスに対して評価される JMESPath 式を指定します。そのため、パスは Result.（または ResponseMetadata.）から始まります。

# Single field
ve sts GetCallerIdentity --query 'Result.AccountId' --output text

# Project a list for the user
ve ecs DescribeInstances --query 'Result.Instances[].{Id:InstanceId,Name:InstanceName,Status:Status,Zone:ZoneId}' --output table

# Filter, then pick IDs into a shell variable
ids=$(ve ecs DescribeInstances --query "Result.Instances[?Status=='RUNNING'].InstanceId" --output text)

# Length / existence checks
ve vpc DescribeVpcs --query 'length(Result.Vpcs)' --output text

目安：

• レスポンスを（エージェントである）あなたが読む必要がある場合は json のままにし、ユーザーに表示する内容に限って table／yaml に切り替えます。
• ResponseMetadata.Error を確認する前に、書き込み／破壊的な呼び出しを --query で無出力にしないでください。失敗時もエラーオブジェクトは出力されます。
• --query は出力内容をフィルタリングするものであり、リクエスト内容は変わりません。ページネーション（NextToken、PageNumber）も変更されません。

レスポンス形式

// Success
{ "ResponseMetadata": { "RequestId": "..." }, "Result": { ... } }

// Failure
{ "ResponseMetadata": { "Error": { "Code": "...", "Message": "..." } } }

エラー処理

安全ポリシーによるブロックまたは確認要求（§2）がある場合、リクエストは送信されていません。§2 の説明に従って対処してください。これは権限エラーでも CLI の異常でもないため、権限の診断やフィードバックの案内を開始してはいけません。

ネイティブの ve <service> <Action> コマンドまたは拡張ヘルパーが失敗した場合、あるいはレスポンスに ResponseMetadata.Error が含まれる場合は、エラーの診断やユーザーへの回答の前に、references/common-errors.md を最後まで読んでください。一部の検索結果、該当行、抜粋だけでは要件を満たしません。ve tosutil／ve arkcli／ve volclog の失敗については、選択した製品スキルとネイティブの子エラー形式に従ってください。

まず、エラーをリクエスト形式、依存関係の不足、アカウントの状態、サービスの有効化、実名確認、購入資格、または権限関連に分類します。製品固有のエラーについては、該当するサービスの注記も読んでください。権限エラー（AccessDenied、NoPermission、RoleNotExist、Forbidden、または STS 関連の失敗）の場合は、volcengine-troubleshooting スキルを有効にし、そのアカウント権限の診断機能を使って根本原因を特定し、ユーザーが修正できるよう案内してください。

CLI の異常や未解決のタスクについては、volcengine-troubleshooting の進行を妨げないフィードバックのガイダンスに従ってください。主なタスクを続行し、任意の案内は自然な要約の中に含めます。ユーザーから求められたフィードバックは volcengine-feedback に従ってください。利用できない場合は、スキルをインストールしたり、フィードバックのためにタスクをやり直したりせず、現在の会話でフィードバックフォームを使用してください。

非同期リソースの作成にはポーリングが必要です

一部のリソース（VKE クラスター、RDS インスタンス、ECS インスタンスなど）の作成には数分かかります。作成後、リソースが目的のステータスになるまで Describe エンドポイントをポーリングしてから、次に進んでください。

VPC 作成直後にサブリソース（セキュリティグループなど）を作成すると、InvalidVpc.InvalidStatus が発生することがあります。サブリソースは順番に作成する（まずサブネット、次にセキュリティグループ）か、数秒待ってから再試行してください。

# General polling pattern: check every 30 s, give up after a deadline, stop on API failure
max_attempts=40   # 40 x 30 s = 20 min; size it to the resource type
for attempt in $(seq 1 "$max_attempts"); do
  if ! cur_status=$(ve <svc> Describe<Resource> --<IdParam> "xxx" --query 'Result.<Path>.Status' --output text 2>&1); then
    echo "describe failed: $cur_status"; break        # classify with common-errors.md, do not keep looping
  fi
  echo "$(date +%H:%M:%S) $cur_status"
  case "$cur_status" in
    Running) break ;;
    Error|Failed|Deleted) echo "resource entered $cur_status"; break ;;
  esac
  [ "$attempt" -eq "$max_attempts" ] && echo "timed out waiting for Running"
  sleep 30
done

Result.<Path> と終了ステータス名は製品ごとに異なります。--help --detail とサービスの注記から確認し、Running と決めつけないでください。

---

5. ネイティブ OpenAPI 実行フロー（概要）

1. Set caller metadata for this execution -> choose the confirmation mode (§2) -> verify credentials -> GetCallerIdentity -> confirm region
2. Understand the task: is the user querying or making changes?
3. Locate the API: ve --help first -> find_api.py as fallback -> --force if the metadata lacks it
4. Retrieve parameters: --help, then --help --detail for write/destructive actions
5. Query dependent resources: use Describe*/List* (with --query to pick IDs) to obtain required IDs
6. Read operation -> execute directly and display results (--output table for lists)
   Write operation, built-in rules -> show command -> DryRun (if supported) -> user confirmation -> execute
   Write operation, safety policy  -> execute -> if blocked or held for confirmation, follow §2
7. Parse the response and report results to the user

---

6. サービス固有の注意事項

サービス固有の問題に遭遇した場合は、対応する注意事項ファイルを参照または更新してください。

• よくあるエラー：references/common-errors.md
• コンソールログイン手順（ve_login_remote.sh、終了コード、ルール）：references/console-login.md
• Cloud Control API（cloudcontrol）：references/cloudcontrol.md
• ECS：references/ecs.md
• VPC：references/vpc.md
• CR：references/cr.md
• ALB：references/alb.md
• CLB：references/clb.md
• VKE：references/vke.md
• veFaaS：references/vefaas.md
• RDS：references/rds.md
• メッセージキュー：references/mq.md
• ストレージ API：references/storage.md
• オブザーバビリティ：references/observability.md
• DNS／エッジ：references/dns-edge.md
• IAM：references/iam.md
• KMS：references/kms.md
• Redis：references/redis.md
• NAT ゲートウェイ：references/natgateway.md
• EBS：references/ebs.md
• 拡張 API（--force のレシピとクエリ／ボディのヘルパー）：references/extend-apis.md