volcengine-tls

Volcengine TLS（volclog）

volcengine-tls/ve-tls-cli の volclog-core を基にしています（Apache-2.0）。コマンド例は上流のネイティブな volclog ... 形式のままです。ve >= 1.1.11 が必要なため、実行時は ve volclog ... とし、それ以降の引数は変更しないでください。

概要

このスキルは、エージェント専用の増分ナレッジにのみ使用してください。

このファイルは、環境固有のブートストラップ用メモや API リファレンスではなく、volclog の汎用的な基本動作モデルとして扱ってください。このファイルは動作の要約であり、詳細についてはリファレンスが正式な情報源です。volclog tool describe ... または volclog workflow describe ... ですでに質問への答えが得られる場合は、そこで確認を止め、その契約に従ってください。ここに重複するガイダンスを追加しないでください。

操作方針

• tool describe または workflow describe を契約上の正しい情報源として扱ってください。まず tool describe または workflow describe を確認してください。
• プロファイル設定は、リージョンを探し回る作業ではなく、ランタイムセレクターの問題として扱ってください。
• ランタイムセレクターとして、アクティブなプロファイル、明示的な --profile <name>、単発の --secrets-file、context.secrets_file、またはプロセススコープの環境認証情報を考慮してください。
• 公開 API には tool、CLI が管理するオーケストレーションには workflow を使用し、raw はメソッドとパスがすでに判明している場合にのみ使用してください。
• 1 回の呼び出しで利用できる App、LogApp、Trace、TraceScore の機能には tool を使用してください。CLI が管理する複数回の呼び出しをまたぐ展開には、workflow app.resolve-resources または app.resolve-topic-ids のみを使用してください。
• tool exec または workflow exec がすでにサポートしている場合は、--input '{...}' などの構造化 JSON 入力を優先してください。

ランタイムセレクターモデル

• 利用可能なランタイムセレクターを確認するまでは、実行環境が不明であるものとして扱ってください。
• アクティブまたはデフォルトのプロファイルがタスクに適したセレクターだと決めつけないでください。
• ローカルのプロファイル探索が実際に必要な場合にのみ、volclog configure list を実行してください。
• region は、契約またはタスクで明示的にオーバーライドが必要とされている場合にのみ使用してください。エンドポイントやドメインから推測しないでください。
• --profile／context.profile と --secrets-file／context.secrets_file は、ビジネス入力フィールドではなくランタイムセレクターです。
• AK／SK やトークンの値を、プロンプト、メモリ、リクエスト成果物、スキルの内容で読み取ったり、表示、エクスポート、永続化したりしないでください。

標準的なエージェントのループ

検出 -> 説明 -> 実行 -> 結果の確認

1. ランタイムセレクターを決定します。
   • この実行でプロファイル、シークレットファイル、環境認証情報のどれを使用するか決めます
   • ローカルのプロファイル探索が重要な場合は、volclog configure list を実行します
   • 選択したセレクターをコマンドまたはコンテキストで明示します
2. 呼び出し可能な機能を検出します。
   • volclog tool list
   • volclog tool list <group>
   • volclog workflow list <group>
3. 契約を確認します。
   • volclog tool describe <group.action>
   • ネストされたリクエストを作成する場合、またはコンパクト出力で想定されるオプションフィールドが省略されている場合は、volclog tool describe <group.action> --view full を使用します
   • コンパクトビューは検出用の要約、フルビューはリクエスト作成用の契約として扱います
   • volclog workflow describe <group.command>
4. 構造化入力で実行します。
   • volclog tool exec <group.action> --input '{...}'
   • volclog workflow exec <group.command> --input '{...}'
   • volclog raw --method <METHOD> --path <PATH> --body '{...}'
5. 次の順序で結果を確認します。
   • status（"success" または "failed"）
   • summary.deliveryMode
   • フラットな error オブジェクト（status が "failed" の場合）
   • data 内のビジネスフィールド（status が "success" の場合）

参照資料のエスカレーション

• デフォルトでは、参照ファイルをすべて読む必要はありません。
• まず tool describe または workflow describe を読みます。
• describe または list を確認しても操作対象が不明な場合に限り、references/routing.md を読みます。
• タスクが複数の呼び出しにまたがり、停止条件が必要な場合に限り、references/sops.md を読みます。
• コントラクトが判明した後もランタイムの動作、配信モード、または復旧方針が不明な場合に限り、references/best-practices.md を読みます。
• contract_cache_hint と contract_digest は、tool describe または workflow describe の出力に含まれています。contract_cache_hint.safe_scope と contract_cache_hint.refresh_when を読み、同じ CLI ビルドで同じ contract_digest が引き続き報告されている場合にのみ、キャッシュ済みの結果を再利用します。
• 1つの参照資料で現在の不明点が解消されたら、そこで止めます。「念のため」にすべての参照資料を読み続けないでください。

主なルール

• コマンド名、ツール ID、ワークフロー ID、JSON フィールド、出力形式を推測してはいけません。
• アクション ID がまだ不明な場合は、推測する前に volclog tool list <group> または volclog workflow list <group> を実行します。
• 操作の risk、recovery、usage_constraints は、以下の汎用的な復旧マップより優先されます。
• high-risk-retry は、再試行のリスクが高いことを示す警告として扱います。結果が曖昧な場合は、コントラクトで指定された get／describe／list アクションによってのみ照合してください。それ以外の場合は、自動で再試行せず停止してエスカレーションします。
• 人間向けのショートカットコマンドを、エージェントの主要な実行フローとして使用しないでください。
• tool describe または workflow describe にすでに記載されているスキーマの詳細を繰り返さないでください。
• シェルでの実行経路が短く見えるという理由だけで、有効な tool exec または workflow exec リクエストを、フラグの多いショートカット形式に作り直さないでください。
• スキーマやフィールドのパスを特定するだけの目的で、volclog の出力を jq または grep に渡さないでください。
• まず JSON エンベロープ全体を読みます。--jmes-filter を使うのは、必要なエンベロープのパスがすでに分かっている場合に限ります。
• 書き込みや破壊的変更の前には、raw、tool exec、または workflow exec でのみ --dry-run を優先します。
• --dry-run はコントラクトまたはプランの検証として扱い、ビジネスクエリが正しいことの証明とはみなしません。
• フィールド名が一意である場合は、手動でネストする前にフラットな JSON 入力を優先します。

エラー復旧クイックマップ

失敗したエンベロープの後のデフォルトの最初の対応としてこの表を使うのは、操作の risk、recovery、usage_constraints を読んだ後にしてください。操作の契約が優先されます。以下のクイックアクションだけでは実行時の詳細が不足する場合に限り、references/best-practices.md を読んでください。

シグナル	次のアクション
error.kind=validation	describe に戻り、まず形状またはセレクターの問題を修正します。
error.kind=auth または 401	ランタイムセレクター、次に認証情報、最後にエンドポイントまたはリージョンのオーバーライドを再確認します。
403 Forbidden	権限の検索範囲を広げる前に、テナントまたはプロファイルの整合性を再確認します。
error.kind=usage	tool list または workflow list を再実行します。エイリアスを推測してはいけません。
error.kind=unsupported_feature	error.hint を読み、未サポートのフラグを削除するか、指定されたサーフェスに切り替えます。LogApp 以外の Topic の解決では、app.resolve-resources に切り替えてください。
error.kind=incompatible_flags	競合しているフラグのいずれかを削除して再実行します。
error.kind=filesystem	再試行する前に、--output-dir、ローカルパス、または権限を修正します。
error.kind=decode	error.hint を読み、誤ったフィルターまたはプロジェクションがあれば削除してから、フィルターなし、または --trace-dir を指定して再実行します。
error.kind=server	error.code と error.requestId を読みます。操作の契約で許可されており、障害が明らかに一時的な場合に限り、バックオフして再試行します。
error.kind=config	ホスト側の設定を確認するため volclog doctor を実行し、報告されたランタイムの問題を調べます。
error.kind=unknown	まず error.hint を読み、次に error.message または error.details を読みます。さらに詳細が必要な場合に限り、--dry-run または --trace-dir を指定して再実行します。
ResultStatus=incomplete	件数や空であることを信頼する前に、時間範囲を絞って再実行します。

volclog doctor は、認証情報、エンドポイント、ローカル設定などのホスト／ランタイム設定を確認します。describe の代わりにはならず、ビジネスクエリの意味的な妥当性も検証しません。

大きな結果の処理

• サーフェスの選択と配信方法の選択は分けてください。
• 結果が大きくなる可能性がある場合は、書き込み可能な --output-dir を指定します。
• 実行時に実際に起きたことは、summary.deliveryMode で確認します。
• outputMode、deliveryMode、ファイル配信、--jmes-filter の正確な意味については、ここで重複して説明する代わりに references/best-practices.md を読んでください。

クイックマップ

必要なこと	推奨
公開 API の契約がすでに決まっている	volclog tool describe <group.action> / volclog tool exec <group.action>
CLI ワークフローがすでに決まっている	volclog workflow describe <group.command> / volclog workflow exec <group.command>
アクションまたはワークフローの ID を確認する	volclog tool list <group> / volclog workflow list <group>
サーフェスの選択にヘルプが必要	references/routing.md を読む
複数ステップの実行順序が必要	references/sops.md を読む
App リソースグラフを解決する	volclog workflow describe app.resolve-resources / volclog workflow exec app.resolve-resources
LogApp App の Topic ID を解決する	volclog workflow describe app.resolve-topic-ids / volclog workflow exec app.resolve-topic-ids
ランタイム／エラー／復旧の意味を確認する	references/best-practices.md を読む
正確なメソッド／パスを使う	volclog raw --method ... --path ...
ステートレス実行を認証する	ホストで選択したローカルプロファイル -> 1 回限りの --secrets-file または context.secrets_file
契約の再利用に関する安全性が必要	同じ CLI ビルドが引き続き同じ contract_digest を報告している間のみ、キャッシュ済みの結果を再利用します