huawei-cloud-optv-evolve-management

⚠️ 実行方法（必読）：すべてのスクリプトは skill action=exec を介して実行してください。シェルから直接実行しないでください。

• このスキルでの OptVerse 呼び出しは、すべて KooCLI（コマンドラインエントリー hcloud）経由で行う必要があります。requests やその他の HTTP ライブラリを使った OptVerse OpenAPI への直接呼び出しは禁止されています。
• scripts/ 内のファイルは スキルに同梱されたヘルパーツール（zip_helper.py / cache.py）です。すべてローカルのみで動作するツールであり、KooCLI のサブプロセスは呼び出しません。
• エージェント自身が、一時的な .py スクリプトファイルを作成することは絶対に避けてください。Python で JSON を処理する場合は、python -c "..." によるインライン実行を優先してください。 一時的なスクリプトファイル（.py / .sh など）を作成しないでください。一時的な成果物（zip パッケージ、JSON キャッシュ、スキャン結果）は固定の場所にある .stats/ または OPTV_CACHE_DIR に保存し、使用後は必ず削除してください。 ⚠️ セキュリティルール（必読）：会話、スクリプト、出力で AK / SK を決して公開しないでください。認証情報の有無は hcloud configure list でのみ確認してください。

アルゴリズム自動設計スキル（英語）

概要

Huawei Cloud 科学計算ゾーン — アルゴリズム設計モジュールでの、エンドツーエンドのコード進化：

• アルゴリズムコード、評価器、ベースラインをアルゴリズム設計プロジェクトにアップロードします
• 進化タスクを作成して開始し、進捗を監視して、結果とログを取得します

結果を OBS バケットにアップロードする必要がある場合（任意の手順。デフォルトのシナリオでは省略してください）：

• クロスサービスの信頼アンカーとして IAM Agency を作成／維持します
• アルゴリズム設計モジュールにバケット（OBS）のアクセス許可を付与します

対応言語：

言語	アルゴリズム	評価器	ベースライン
Python	ソースファイル + 関数名	def evaluate(): を含むソースファイル（例：evaluator.py）	def baseline(): を含むソースファイル（例：baseline.py）
C++	ソースファイル + 関数名（進化対象の関数）	コンパイル済み実行可能コマンド（例：build/evaluate <args>）	コンパイル済み実行可能コマンド（評価器と同一でも可）

C++ プロジェクトでは、CreateAlgorithm --build_command を使用して、アップロードされた .cpp ファイルを実行可能ファイルにコンパイルします。C++ では evaluator_file / evaluator_baseline フィールドを空欄にし、コマンド名だけを指定します。

ディレクトリ構成

skills/ai/optverse/huawei-cloud-optv-evolve-management/
├── SKILL.md                # This file (English)
├── references/              # Topic-split documentation
│   ├── readme.md
│   ├── api-mapping.md
│   ├── prerequisites.md
│   ├── parameter-format.md
│   ├── iam-policies.md
│   ├── iam-agency.md
│   ├── agency-policy.md
│   ├── language-python.md
│   ├── language-cpp.md
│   ├── algorithm-workflow.md
│   ├── evolve-task-workflow.md
│   ├── result-logs-status.md
│   ├── troubleshooting.md
│   ├── verification-method.md
│   ├── cli-installation-guide.md
│   └── plan-maintenance.md
├── scripts/                 # Local tools (no hcloud calls)
│   ├── readme.md
│   ├── precheck.sh
│   ├── precheck.ps1
│   ├── cache.py
│   ├── build_task_url.py
│   └── zip_helper.py
├── templates/               # evaluator / baseline / algorithm source code skeletons
│   ├── readme.md
│   ├── python/
│   │   ├── evaluator.py
│   │   ├── baseline.py
│   │   └── algorithm.py
│   └── cpp/
│       ├── evaluator.cpp
│       └── baseline.cpp
└── .stats/                  # Locally maintained caches (algorithm_id, task_id)
    ├── algorithm_id.csv
    └── task_id.csv

references、scripts、templates の 3 つのサブディレクトリは、それぞれの役割に応じて分かれています。references は説明資料、scripts はローカルのみで動作するヘルパーを実行するもの（scripts/readme.md を除く）、templates はアップロード可能なソースを提供するものです。

---

1. 前提条件

最初に必ず行う手順：hcloud OptVerse ... または hcloud IAM ... を呼び出す前に、skill action=exec を介して scripts/precheck.sh（Linux / Git Bash / WSL）または scripts/precheck.ps1（Windows PowerShell）を実行してください。precheck では、① KooCLI のインストール、② AK/SK の設定、③ リージョンの設定、④ OptVerse API への接続を確認します。

1.0 ワンショット環境チェック（最初に必須）

⚠️ Windows のシェル選択：powershell（システムにインストールされている Windows PowerShell 5.1）を使用してください。このスキルでは、PS 5.1 と precheck.ps1 の組み合わせで、5/5 件のチェックに合格することを確認済みです。 Windows では、既定で bash を使用しないでください。where bash の結果が C:\Users\<user>\AppData\Local\Microsoft\WindowsApps\bash.exe になることがあります（これは WSL がない場合に「WSL をインストール」と表示したまま停止する WSL ランチャーのスタブです）。WSL bash はこのスキルでは検証されていません。

タスクを開始する前に、skill action=exec で precheck スクリプトを一度実行する必要があります（5 件のチェックをまとめて実行します）。

# Windows PowerShell (via skill action=exec; preferred)
powershell scripts/precheck.ps1

# Git Bash / MSYS2 bash (via skill action=exec; last resort — WSL bash not verified)
bash scripts/precheck.sh

出力：✅ / ⚠️ の概要（既定では summary モード。チェックごとの詳細を表示するには CHECK_OUTPUT_MODE=detail を設定します）

終了コード：0 = すべて合格、1 = 1 件以上 FAIL

チェック対象（§1 のサブセクションとの対応）：

precheck 項目	対応先
hcloud コマンド（PATH 内）	§1.1 KooCLI のインストール
hcloud version（初回実行時の規約への同意）	§1.1 KooCLI のインストール
hcloud configure list（認証情報の設定）	§1.2 認証情報（AK/SK）
region の設定（環境変数／プロファイル）	§1.2 認証情報、A. Project ID など
OptVerse への接続（ListBuckets による確認）	§1.5 Agency とバケットの認可（前提条件：接続が正常であること）

チェック対象外（別途確認してください）：

• §1.3 Python インタープリター（precheck は python を確認しません）
• §1.4 IAM 権限（precheck は IAM アクションを検証しません）
• §1.5 Agency の作成とバケットの認可（precheck は接続のみを確認し、Agency の作成やバケットの認可は実行しません）

1.0.1 代替シェルの表

powershell を使用できない場合、記載されている代替手段は bash（Git Bash／MSYS2／Linux）のみです。WSL bash はこのスキルでは検証されていないため、使用しないでください。

確認項目	意味	推奨する precheck
PATH 内の powershell	Windows PowerShell 5.1（システムにインストール済みで、広く利用されています）	powershell scripts/precheck.ps1
PATH 内の bash	Git Bash／MSYS2／Linux	bash scripts/precheck.sh

1.0.2 手動での代替 5 行チェック

precheck.sh／precheck.ps1 を実行できない場合は、references/prerequisites.md §2.1「5 行の手動チェック」に記載されている 5 つの手動確認コマンドを参照してください。

1.1 KooCLI のインストール（hcloud CLI）

インストール、認証情報、ネットワークの完全な確認については、references/cli-installation-guide.md を参照してください。簡易確認には hcloud version を実行します（想定される出力は 当前KooCLI版本:7.2.12.1 以降です）。初回実行時は、規約への同意を求められることがあります。非対話型スクリプトでは、y を入力してください。

1.2 認証情報（AK/SK）

AK/SK がまだ設定されていない場合は、hcloud configure init を対話形式で実行し、AK／SK／region／project ID などを入力してください。

設定後、接続を確認します。

hcloud configure list
hcloud OptVerse ListBuckets --cli-region=<region> --cli-output=json
hcloud IAM ListAgencies --domain_id=<my-account-id> \
  --cli-region=<region> --cli-output=json

セキュリティ規則：会話、スクリプト、出力に AK/SK を決して含めないでください。

1.3 Python インタープリター

• デフォルト：システムの python
• 評価に必要なサードパーティパッケージは、アルゴリズムの --env フィールドを使用してインストールします。完全な pip install <pkgs> コマンドを指定してください（CreateAlgorithm に渡されます）。評価の前に、プラットフォームがこのコマンドを実行します。

⚠️ Windows PowerShell と hcloud の致命的な組み合わせ：powershell_exec hcloud ... --project_id=$AID は、リテラル文字列 $AID を KooCLI に渡します（PowerShell の変数はプロセス間で展開されません）。 その結果、「invalid parameter value」という分かりにくいエラーが発生します。正しい方法：必ず §6.8 の skill action=exec argv 配列形式を使用し、変数を argv 配列で明示的に渡してください。

❌  powershell_exec hcloud OptVerse ShowTaskDetails --project_id=$AID --evolve_task_id=$TID
✅  skill action=exec --name huawei-cloud-optv-evolve-management \
       --command ["hcloud","OptVerse","ShowTaskDetails",
                  "--project_id="+AID,"--evolve_task_id="+TID,"--cli-region="+REGION]

• Windows PowerShell ユーザー：このドキュメントの冒頭にある Execution Method ルールと、以下の §6.8 を参照してください。hcloud は必ず skill action=exec の argv 配列形式で呼び出してください。powershell_exec hcloud ... は使用しないでください。KooCLI サブプロセス内で PowerShell の変数展開（$AID / $TID）を行うと、引数の値が気付かないうちに破損し、「invalid parameter value」という分かりにくいエラーが発生することがあります。

1.4 IAM 権限

必要なアクションは references/iam-policies.md に記載されています。動作確認にはシステムポリシーの OptVerse FullAccess と Security Administrator が使用できます。本番環境では、このファイルに記載されているカスタムポリシー JSON を使用してください。

1.5 Agency とバケットの認可（任意）

evolve タスクの結果を独自の OBS バケットにアップロードする必要がある場合は、まず IAM agency を作成してから、バケットを認可する必要があります。結果をアップロードする必要がない場合（OptVerse コンソールまたは hcloud で進捗と結果を確認するだけの場合）は、どちらの手順も省略できます。その場合、CreateEvolveTask --output_path は空欄のままにします。

フロー図と具体的なコマンドは、§4.2 §A「一度だけ行う準備」に記載されています。詳しい手順は references/iam-agency.md および references/agency-policy.md を参照してください。

判断方法：OptVerse のコンソールまたは hcloud で evolve の結果を確認するだけで、OBS に成果物を保存する必要がない場合は、§A を省略し、--output_path="" を指定して §B.2 を使用できます。

---

2. トリガー

次のいずれかのユーザー要求があった場合、このスキルを有効にします。

• 「evolve タスクを作成」／「evolve タスクを開始」／「evolve タスクを停止／削除」
• 「アルゴリズムコードをアップロード」／「アルゴリズムプロジェクトに評価器を追加」

---

3. 安全性とリスクに関する制約

• 破壊的な呼び出しはすべて、2 段階の確認が必要です：コマンドとリスク警告を表示し、ユーザーから明示的な確認を得てから実行してください。対象は IAM DeleteAgency、OptVerse DeleteAlgorithm、OptVerse DeleteEvolveTask、OptVerse BatchDeleteEvolveTask、OptVerse RevokePermission です。
• アップロード済みファイルの名前は変更しないでください。--file_path に渡すファイルパスは、os.path.basename(local_file) と一致している必要があります。
• 時間ベースの効率関数では concurrency = 1 を使用してください：--evaluator_max_workers=1 および --search_max_workers=1。
• 認証情報の安全性：値を表示せず、hcloud configure list で設定の有無だけを確認してください。
• C++ プロジェクトでは build_command の指定が必要です。指定しない場合、evaluator.cpp／baseline.cpp／algorithm.cpp を実行可能コマンドにコンパイルできません。

---

4. 標準ワークフロー

4.1 デフォルトのシナリオ（OBS へのアップロードなし）

┌──────────────────────────────────────────────────────────────────────┐
│ [1] Environment & connectivity                                       │
│     hcloud version / hcloud configure list                            │
│     hcloud OptVerse ListBuckets --cli-region=<region>                 │
├──────────────────────────────────────────────────────────────────────┤
│ [2] Create algorithm project                                          │
│     hcloud OptVerse CreateAlgorithm                                    │
│       --name=… --lang=python|c++                                       │
│       [--build_command="…"]  # required for C++                       │
├──────────────────────────────────────────────────────────────────────┤
│ [3] Upload algorithm + evaluator + baseline                           │
│     hcloud OptVerse SaveAlgorithmFile --file_path=<…> (multiple times) │
│     or hcloud OptVerse ImportAlgorithmFile --file=<zip>                │
├──────────────────────────────────────────────────────────────────────┤
│ [4] Create evolve task (output_path blank)                            │
│     hcloud OptVerse CreateEvolveTask --output_path="" --description=… │
├──────────────────────────────────────────────────────────────────────┤
│ [5] Start the task                                                    │
│     hcloud OptVerse StartEvolveTask --evolve_task_id=…                │
├──────────────────────────────────────────────────────────────────────┤
│ [6] Poll status / fetch results                                       │
│     hcloud OptVerse ShowTaskRunningDetails --type=…                   │
│     hcloud OptVerse ShowTaskResultCommit --type=CODE …                │
├──────────────────────────────────────────────────────────────────────┤
│ [7] (optional) Stop / delete the task (delete needs two-step confirm)  │
│     hcloud OptVerse StopEvolveTask / DeleteEvolveTask                │
└──────────────────────────────────────────────────────────────────────┘

4.2 オプションの方法：結果を OBS にアップロードする

アップロードする場合（つまり、CreateEvolveTask --output_path="obs://<bucket>/<prefix>" を使用する場合）、初回のみ必要なエージェンシーの設定とバケット認可の設定は、次のドキュメントに記載されています。

• references/agency-policy.md — OptVerse AuthorizePermission によるバケット認可
• references/iam-agency.md — エージェンシーの作成／アタッチ／照会

エージェンシーは任意です：OptVerse コンソールまたは hcloud で進化計算の結果を確認するだけの場合は、エージェンシーの設定を省略し、--output_path="" を使用してください（§4.1 のデフォルトシナリオを参照）。

4.3 参考：公式サンプルアルゴリズムと algorithm_id の形式

プラットフォームには、参考およびアドホックなデバッグ用に、公式サンプルアルゴリズムが 3 つ用意されています。

algorithm_id	アルゴリズム
0	Sort
1	CVRP
2	CirclePacking

algorithm_id には 2 つの形式が共存しています：

• 公式サンプル：短い数値文字列 id=0 ／ id=1 ／ id=2（ハイフンなし）
• 自作プロジェクト：ハイフン付きの uuid。例：44d5914f-e3cc-406f-aefc-c04913493bec

元の形式は必ずそのまま保持してください。自作プロジェクトの uuid からハイフンを削除して短い ID として渡すと、evolve.01050004 Algorithm id does not exist エラーが発生します。

---

5. コマンド早見表

⚠️ 厳守事項（すべての hcloud コマンド）：すべての hcloud パラメーターは、必ず --key=value 形式を使用してください。スペース区切り形式は禁止です。

理由：--key=value は hcloud サブプロセスに文字列どおり渡されます。スペース区切り形式（例：--project_id xxx）はシェルによるトークン分割に依存するため、プラットフォーム、PowerShell の argv 配列、Git Bash のエスケープ処理をまたぐと、気付かないうちに動作しなくなり、「必須オプションがありません」または「パラメーター値が無効です」というエラーが発生します。

失敗につながるアンチパターン（以下の形式は使用しないでください）：

❌ 誤った形式	失敗内容
--project_id xxx（スペース区切り＋位置引数）	KooCLI が拒否 → 「必須オプションがありません」
--project_id= $VAR（bash、引用符なし）	bash が --project_id=（空の値）と $VAR（位置引数）に分割します
--project_id=$VAR（Windows PowerShell の子プロセス実行）	PowerShell はサブプロセス内の $VAR を展開しません — $VAR が文字列どおり渡されます
-r cn-east-3（短いオプションと値をスペースで区切る）	一部のコマンドでは拒否されます。-r=cn-east-3 を使用してください

5.1 IAM エージェンシー

詳細は references/iam-agency.md を参照してください。エージェンシー名は必須です：optverse_service_trust。バックエンドのサービスアカウントに指定するポリシーの Action リストについても、同じ参考ドキュメントを参照してください。

5.2 アルゴリズム

# List
hcloud OptVerse ListAlgorithms --limit=10 --cli-region=<region>

# Python project
hcloud OptVerse CreateAlgorithm \
  --name="Algorithm_20260101_120000" --lang="python" --description="…" \
  --cli-region=<region>

# C++ project (with build_command)
hcloud OptVerse CreateAlgorithm \
  --name="Algorithm_cpp_20260101_120000" --lang="c++" --description="…" \
  --build_command="bash ./build.sh" \
  --cli-region=<region>

# Details
hcloud OptVerse ShowAlgorithm --project_id=<project_id> --algorithm_id=<aid> --cli-region=<region>

# Directory
hcloud OptVerse ListDirectoryByAlgorithmId --project_id=<project_id> --algorithm_id=<aid> --cli-region=<region>

# Upload single file (must fetch last_update_time first via ShowAlgorithm)
hcloud OptVerse SaveAlgorithmFile --project_id=<project_id> --algorithm_id=<aid> \
  --file=./evaluator.py --file_path=evaluator.py --last_update_time=<ms> \
  --cli-region=<region>

# Delete (dangerous, requires two-step confirmation)
hcloud OptVerse DeleteAlgorithm --project_id=<project_id> --algorithm_id=<aid> --cli-region=<region>

5.3 進化計算タスク

# Python
hcloud OptVerse CreateEvolveTask \
  --project_id=<project_id> --algorithm_id=<aid> --name=… --description=… --output_path=… \
  --evaluator_file=evaluator.py --evaluator_func_name=evaluate \
  --evaluator_baseline=baseline.py --evaluator_baseline_func_name=baseline \
  --evaluator_parameter.search_iterations=10 \
  --evaluator_parameter.search_population_size=4 \
  --evaluator_parameter.search_max_workers=2 \
  --evaluator_parameter.evaluator_max_workers=2 \
  --evaluator_parameter.smaller_better=true \
  --evaluator_parameter.llm_models.1=GLM-5 \
  --cli-region=<region>

# C++
hcloud OptVerse CreateEvolveTask \
  --project_id=<project_id> --algorithm_id=<aid> --name=… --description=… --output_path=… \
  --algorithm_file=sort_algorithm.cpp --algorithm_func_name=sort_array \
  --evaluator_file="" --evaluator_func_name="build/evaluate <args>" \
  --evaluator_baseline="" --evaluator_baseline_func_name="build/evaluate <args>" \
  --evaluator_parameter.smaller_better=true \
  --evaluator_parameter.llm_models.1=GLM-5 \
  --cli-region=<region>

# Start
hcloud OptVerse StartEvolveTask --project_id=<project_id> --evolve_task_id=<tid> --cli-region=<region>

# Status
hcloud OptVerse ShowTaskDetails --project_id=<project_id> --evolve_task_id=<tid> --cli-region=<region>

# Progress / summary / best result / generation stats
# ⚠️ --type uses lowercase underscore (4 values: progress / summary / best_result / generation_stats)
hcloud OptVerse ShowTaskRunningDetails --project_id=<project_id> --evolve_task_id=<tid> \
  --type=progress --cli-region=<region>

# Results
hcloud OptVerse ShowTaskResultList   --project_id=<project_id> --evolve_task_id=<tid> --cli-region=<region>
# ⚠️ --type uses UPPERCASE (3 values: CODE / SUMMARY / INSIGHT)
# ⚠️ `--type=CODE` returns a **base64-encoded string** (NOT plaintext); SUMMARY / INSIGHT are plaintext
hcloud OptVerse ShowTaskResultCommit --project_id=<project_id> --evolve_task_id=<tid> \
  --commit_id=<cid> --iteration=<n> --type=CODE --cli-region=<region>
# --iteration=<n> is REQUIRED; <n> is the iteration segment in "sample_<n>_<fp>"
# Or auto-derive via: python scripts/cache.py get-iteration --commit-id "$COMMIT"

# Stop / delete (delete requires two-step confirmation)
hcloud OptVerse StopEvolveTask  --project_id=<project_id> --evolve_task_id=<tid> --cli-region=<region>
hcloud OptVerse DeleteEvolveTask --project_id=<project_id> --evolve_task_id=<tid> --cli-region=<region>

⚠️ --type= の大文字・小文字のルールは異なります：

• ShowTaskRunningDetails --type= は小文字のアンダースコア形式（progress ／ summary ／ best_result ／ generation_stats）を使用します
• ShowTaskResultCommit --type= は大文字（CODE ／ SUMMARY ／ INSIGHT）を使用します

5.4 バケット／認可

hcloud OptVerse ListBuckets --project_id=<project_id> --cli-region=<region>
hcloud OptVerse AuthorizePermission --project_id=<project_id> --bucket=<bucket> --cli-region=<region>
hcloud OptVerse RevokePermission  --project_id=<project_id> --bucket=<bucket> --cli-region=<region>
hcloud OptVerse ListPermission   --project_id=<project_id> --cli-region=<region>

5.5 タスク／アルゴリズムへの直接 URL

💡 URL の機能：タスクの実行前または実行後に python scripts/build_task_url.py -r <region> --task-id <tid> を呼び出すと、コンソールへの直接 URL を作成できます。デフォルトのブラウザーで開くには、--open を追加してください。

# Just print the URL
python scripts/build_task_url.py -r <region> --task-id <tid>

# Print + launch in default browser (Windows / Linux / macOS)
python scripts/build_task_url.py -r <region> --task-id <tid> --open

パラメーター：

• -r / --region は必須です（例：cn-east-3）。他のリージョン（テスト環境）では、最初に export TEST_ENV_REGION=<region> TEST_ENV_DOMAIN=<domain> を実行する必要があります
• --task-id または --algorithm-id のいずれかが必須です。前者は進化計算タスクの詳細ページ、後者はアルゴリズムプロジェクトのページを作成します
• --open は、グラフィカルデスクトップが検出された場合にのみブラウザーを開きます。ヘッドレス環境／X11 のない SSH 環境／Windows サービスセッションでは、「URL を手動で開いてください」と表示して、コード 1 で終了します
• --quiet は URL の出力を抑制します（ブラウザーを開くだけにする場合は、--open と併用してください）

詳細は scripts/build_task_url.py のヘッダーを参照してください。

---

6. 主な制約（運用）

6.1 言語ごとの評価器／ベースラインの意味

フィールド	Python	C++
--algorithm_file	evolution 配下の Python ソースファイル	// EVOLVE_START/END マーカーを含む C++ ソースファイル
--algorithm_func_name	関数名（例：sort_algorithm）。アルゴリズムファイルに # EVOLVE_START / # EVOLVE_END が含まれている場合は省略できます（プラットフォームがマーカー内の def から自動抽出します）	関数名（例：sort_array）。起動コマンドではありません
--evaluator_file	評価器のソースパス（ベースラインと同じファイルでもかまいません）	空欄のままにします
--evaluator_func_name	関数名 evaluate（デフォルト）	コンパイル済み実行ファイルのコマンド。例：build/evaluate <args>
--evaluator_baseline	ベースラインのソースパス（evaluator_file と同じでもかまいません）	空欄のままにします
--evaluator_baseline_func_name	関数名 baseline（デフォルト）	コンパイル済み実行ファイルのコマンド（評価器と同じでもかまいません）

C++ の evaluator／baseline 実行ファイルは、標準出力に単一の浮動小数点数を出力し、その後に改行を出力する必要があります。

実地検証済み：evaluator_file と evaluator_baseline は同じファイルでもかまいません（関数名は異なる必要があります）。

必須フィールドの3層分類（CreateEvolveTask の前にエージェントが自己チェック）

6フィールドの表全体については、references/parameter-format.md §7「CreateEvolveTask の必須フィールドの3層分類」を参照してください。同じ3つの分類（Agent must ask user／hcloud param must be passed／hcloud value must be non-empty）が記載されています。

6.2 C++ では // EVOLVE_START / // EVOLVE_END が必要です

進化対象の関数は、これらのマーカーで囲む必要があります。プラットフォームはマーカー間のコードのみを置き換えます。マーカー外のコード（main を含む）は保持されます。テンプレートと注意事項の全体については、references/language-cpp.md を参照してください。

6.3 アップロードのたびに content_update_at を更新します

SaveAlgorithmFile／ImportAlgorithmFile の --last_update_time は、アルゴリズムの content_update_at と完全に一致している必要があります。一致しない場合、evolve.01050007 が発生します。アップロードのたびに ShowAlgorithm を再実行してください。

6.4 description は LLM へのプロンプトです

プロンプトとして記述してください。

1. 役割（例：「あなたは…の専門家です」）
2. 背景（解決する問題）
3. 目標（より速く／より正確に／より短く／より大きく）
4. 主な制約
5. 出力形式（任意）

例：

• ソート：「あなたは、高速で効率的なソートアルゴリズムの設計に精通しています。正確かつ高速なソートアルゴリズムを作成してください。」
• CVRP：「あなたは、経路計画の専門家です。顧客の集合と、容量に制限のある車両群が与えられた場合、総コストを最小化することを目的として、各ステップで次のノードを選択する新しいアルゴリズムを設計してください。」

6.5 時間ベースの効率評価では並行数を1にします

評価器が時間を計測する場合：

--evaluator_parameter.evaluator_max_workers=1 --evaluator_parameter.search_max_workers=1

6.6 smaller_better

指標の方向	smaller_better	ベースラインの目標
大きいほど良い（精度）	false	ベースラインはより小さい値にします
小さいほど良い（時間）	true	ベースラインはより大きい値にします

6.7 破壊的な呼び出しでは2段階で確認します

About to execute:
  hcloud OptVerse DeleteEvolveTask --project_id=<project_id> --evolve_task_id=<tid> --cli-region=<region>
Impact: results lost, future callbacks will fail immediately.
Continue? [y/N]

6.8 クロスプラットフォームでの呼び出し原則

基本原則：クロスプラットフォームでの安定性は、単一の「標準的な呼び出し形式」ではなく、次の3つの鉄則によって実現します。

1. すべての OptVerse / IAM 呼び出しは hcloud <Service> <Op>（KooCLI サブプロセス）を経由します。HTTP OpenAPI を直接呼び出してはいけません。
2. パラメーターには argv 配列形式を使います（シェルのエスケープや、シェル間の信頼性の低さを回避できます）。
3. --key=value 形式を使い、--key value のようにスペースで区切ってはいけません。

エージェント／スキルランタイムによって「呼び出し形式」の構文は異なります。以下の表は、優先順位の高い順に並べています。

スタイルの組み合わせ（呼び出しスタイル＋パス方式）	呼び出し例	備考
スキルランタイムラッパー＋スキル URI（推奨）	skill action=exec --name <skill> --command ["powershell","-File","skill://scripts/precheck.ps1"]	スキルランタイムが skill:// をスキルパッケージのルートに自動解決するため、シェル間で安定します
スキルランタイムラッパー＋絶対パス（フォールバック）	skill action=exec --name <skill> --command ["powershell","-File","/abs/path/scripts/precheck.ps1"]	スキルランタイムが skill:// をサポートしていない場合に使用します
シェルを直接実行＋相対パス（cwd がスキルのルートである必要があります）	powershell scripts/precheck.ps1	bash／PowerShell のツールを直接呼び出す方法です。cwd がすでにワークスペースを指している必要があります
Python の直接フォーク（推奨しません）	python -c "import subprocess; subprocess.run(['hcloud',...])"	エージェントフレームワークの分離／キャッシュのセマンティクスを迂回します

⚠️ 使用できるスタイルは、エージェントフレームワークによって異なります（ドキュメントを参照してください）。どのスタイルでも、3つの鉄則を必ず守ってください。

アンチパターン（どのスタイルでも禁止）

❌ アンチパターン	問題点
requests.post('https://optverse...', json=...) で OpenAPI を直接呼び出す	KooCLI の認証／エラー処理／リトライ／--debug ログを迂回します。「OpenAPI 直接呼び出し」の越えてはならない一線に抵触します
--key value のようにスペースで区切る	bash では --key=（空の値）と value（独立したトークン）に分割されます。PowerShell では $VAR が展開されません
python -c "import subprocess; ..." で hcloud を自己フォークする	エージェントフレームワークの分離／キャッシュのセマンティクスを迂回します。スキルランタイムのスクリプト呼び出し機構とも一貫しません

ポーリング戦略

CreateEvolveTask（を含む）より前に、エージェントはユーザーに2つのポーリングモードのいずれかを選んでもらう必要があります。CreateEvolveTask／StartEvolveTask の後まで確認を先送りしてはいけません。フローが崩れ、StartEvolveTask の直後にエージェントがポーリングループから抜け出せなくなります。

• （a）エージェントが能動的にポーリング：FINISHED／FAILED／STOPPED になるまで ShowTaskDetails をループします
• （b）ユーザーが自分で照会（推奨）：evolve_task_id と直接リンク（python skill://scripts/build_task_url.py -r <region> --task-id <tid> --open）をユーザーに渡し、必要に応じて後から ShowTaskDetails を照会します。

ポーリングをすぐに開始することは推奨しません（エージェントセッションが長時間占有されるのを防ぐためです）。

---

7. ファイルシステムの規約

7.1 一時ファイル

• スキルディレクトリまたはユーザーのホームディレクトリ内に、一時ファイルを書き込まないでください。
• 自動生成される一時スクリプトは OPTV_CACHE_DIR（デフォルトではスキルの .stats/ フォルダー）に保存し、使用後に削除してください。

7.2 キャッシュファイル

.stats/ は手動で管理します。

• .stats/algorithm_id.csv — 現在アクティブなアルゴリズム ID
• .stats/task_id.csv — このセッションで作成されたすべての進化タスク

7.3 ファイル名の一貫性

⚠️ アップロードしたファイルの名前を変更しないでください。 Python 評価ファイル／ベースラインファイルの名前に厳密な要件はありません。重要なのは、CreateEvolveTask で --evaluator_file／--evaluator_baseline に渡すファイルだけです（プラットフォームはファイル名でインポートします）。C++ プロジェクトでは、build_command によって、--evaluator_func_name／--evaluator_baseline_func_name と一致する名前の実行可能ファイルをコンパイルする必要があります。

8. パラメーターカテゴリのクイックリファレンス

パラメーター構文リファレンス：詳細な --key=value／ネスト／配列／列挙型／サイズ制限／JMESPath の構文は、references/parameter-format.md に記載されています。このセクションは、エージェント向けの簡易的な A／B／C 分類です。

タスクを開始する際、エージェントは以下の 3 つのカテゴリに従って各パラメーターの取得元を判断します。まず A から入力し、次に B を収集し、最後に C のデフォルト値で補います。

8.1 A. 事前設定済み（エージェントが自動取得し、ユーザーには尋ねません）

パラメーター	取得元
--project_id	hcloud configure show の出力、または環境変数 HUAWEI_CLOUD_PROJECT_ID
--cli-region	hcloud configure show の出力、または環境変数 HUAWEI_CLOUD_REGION
--algorithm_id（既存プロジェクト）	ローカルキャッシュ .stats/algorithm_id.csv の algorithm_name をキーに取得します。優先して scripts/cache.py の ensure-algorithm を使用してください
--evolve_task_id（既存タスク）	ローカルキャッシュ .stats/task_id.csv の algorithm_id をキーに取得します。優先して scripts/cache.py の ensure-task を使用してください
--last_update_time	エージェントが hcloud OptVerse ShowAlgorithm を実行して content_update_at を取得し、scripts/cache.py put-lut --lut <ms> で書き込みます。次回以降の呼び出しでは get-lut で読み取ってください

8.2 B. ユーザーへの確認必須（エージェントが推測してはいけません）

開始前にすべてまとめて収集してください。段階的に尋ねてはいけません。

1. 言語：python ／ c++
2. アルゴリズムの目標／プロンプト：何を進化させるか、および制約（--description に指定します）。プロンプトのテンプレートは §6.4 を参照してください
3. アルゴリズムのソースファイルのローカルパス + --algorithm_file + --algorithm_func_name
4. 評価関数のローカルパス + 関数名（Python）／evaluator_func_name コマンド（C++）
5. ベースラインのローカルパス + 関数名（Python）／baseline_func_name コマンド（C++）
6. --build_command（C++ のみ、必須）
7. --bucket + --output_path="obs://..."（結果を OBS にアップロードする必要がある場合のみ。デフォルトのシナリオでは省略してください**）
8. --evaluator_parameter.search_iterations（必須）：進化のラウンド数。--evaluator_parameter.* 構文の詳細は parameter-format.md を参照してください
9. 開始後のポーリング方法（必須）：1 つ選択してください。詳しくは §6.8 クロスプラットフォームの呼び出し原則 を参照してください。長時間のタスクでは、ユーザー自身による照会を推奨します
10. 破壊的操作の 2 段階確認 — §3 を参照してください

8.3 C. エージェントが自動生成（ユーザーは上書きできます。事前に尋ねません）

パラメーター	デフォルトのルール
--name（プロジェクト／タスク）	Algorithm_YYYYMMDD_HHMMSS ／ EvolveTask_<algo-name>_<timestamp>
--description	汎用テンプレート：役割（ドメインの専門家）+ 背景（解決する問題）+ 目標（ユーザー指定：速度／精度／距離／その他）+ 主な制約 + 出力形式（任意）。§6.4 を参照してください
--output_path	デフォルトは ""（アップロードなし）
--evaluator_parameter.search_iterations	デフォルトは 10（初回実行では 3〜5 を推奨）
--evaluator_parameter.search_population_size	デフォルトは 4（3 を推奨）
--evaluator_parameter.smaller_better	時間／距離 → true、精度／ヒット率 → false（評価関数の意味から推定）
--evaluator_parameter.{evaluator,search}_max_workers	時間クラス → 1、それ以外 → 2
--evaluator_parameter.llm_models.1	デフォルトは GLM-5
機関名／ポリシー名（アップロードのシナリオ）	optverse_service_trust ／ policy_ai4s_llma4ad ／ op_svc_oroas_container0

8.4 キャッシュヘルパー

scripts/cache.py はキャッシュファイルの I/O をカプセル化します。コマンドを実行する前に、エージェントは $(python scripts/cache.py ...) を使って <aid> / <tid> を取得します。

AID=$(python scripts/cache.py ensure-algorithm --name "p1test")
TID=$(python scripts/cache.py ensure-task --aid "$AID")

# last_update_time: agent runs hcloud + put-lut explicitly
LUT=$(hcloud OptVerse ShowAlgorithm --algorithm_id="$AID" \
  --cli-region="$REGION" --cli-output=json \
  --cli-query="payload.item.content_update_at")
python scripts/cache.py put-lut --aid "$AID" --lut "$LUT"

# Then later:
LUT=$(python scripts/cache.py get-lut --aid "$AID")

Python モジュールとしても使用できます。

from scripts.cache import (
    ensure_algorithm, ensure_task, get_lut,
    put_algorithm, put_task, put_lut,
)

キャッシュツールのサブコマンド：ensure-algorithm / put-algorithm / ensure-task / put-task / get-lut / put-lut。詳細は scripts/cache.py のヘッダーを参照してください。

cache.py は hcloud を呼び出しません：すべての last_update_time の処理はエージェントがシェル上でオーケストレーションします。cache.py は IAM 権限を必要としない、ローカル専用のツールです。

---

9. Scripts/ の連携

scripts/ には5 つのヘルパースクリプトが含まれています。各スクリプトの詳しい使い方は scripts/readme.md にあります。

• precheck.sh / precheck.ps1：5 項目を一括で確認する環境チェック
• cache.py：<algorithm_id> / <evolve_task_id> / last_update_time 用のローカル CSV キャッシュ
• build_task_url.py：タスク / アルゴリズムのコンソールへの直接 URL を表示（または開く）
• zip_helper.py：ローカル ZIP パッケージング。ImportAlgorithmFile --file=… と組み合わせて使用

その後、すべての業務 API 呼び出しとローカルスクリプトの実行は skill action=exec 経由でディスパッチされます（§6.8 を参照）。

---

10. 得られた知見

hcloud を使ったエンドツーエンドの実行後、次のルールが明らかになりました。

1. 関数名が異なっていれば、evaluator_file と evaluator_baseline は同じファイルを指定できます。
2. 名前が衝突しない限り、algorithm_file と evaluator_file も同じモジュール（または別のモジュール）を指定できます。
3. C++ アルゴリズムのソースには、進化対象の関数を囲む // EVOLVE_START と // EVOLVE_END を必ず含めてください。プラットフォームが置き換えるのはマーカー間のコードだけです。それ以外（main を含む）はすべて保持されます。
4. C++ の algorithm_func_name は関数名（sort_array）であり、起動コマンドではありません。evaluator_func_name はコンパイル済み実行ファイルのコマンド（例：build/evaluate <args>）で、パスやコマンドライン引数を含めることができます。
5. 同じ実行ファイルのコマンドを evaluator_func_name と evaluator_baseline_func_name の両方に使用できます。プラットフォームは進化対象のアルゴリズムソースを置き換えることで両者を区別します。
6. SaveAlgorithmFile / ImportAlgorithmFile の前には毎回 ShowAlgorithm を再実行し、最新の content_update_at を取得してください。古い値を再利用すると evolve.01050007 が発生します。
7. SaveAlgorithmFile は .sh スクリプトに対して失敗します（「未対応のファイル形式」）。複数ファイルからなる C++ プロジェクトでは、必ず ImportAlgorithmFile と ZIP を使用してください。
8. ZIP 内の .gitignore は保持してください。プラットフォームはプロジェクトを git で管理します（ZIP のアップロード時に git init が実行されます）。.gitignore には通常、cmake のビルド生成物を除外するために build / build/ が記載されています。.gitignore がないとビルド出力が git の履歴に入り、後続の cmake 実行が失敗します（例：すでに build/ が存在するため、cmake がクリーンに上書きできない）。
9. ベースラインとの比較値の取得場所：
   • ベースライン値：ShowTaskRunningLog の Baseline Population テーブル内にある Metric[metric_value] = X の行
   • 最良値：ShowTaskRunningDetails --type=best_result の payload.item.value
   • 個体ごとのスコア：ShowTaskResultList の list[].fitness_value
   • 改善率 = (baseline - best) / baseline

エラーの全一覧については、references/troubleshooting.md §4-§5 を参照してください。

---

11. エンドツーエンドの例

Python と C++ のエンドツーエンドの例（CLI コマンド一式を含む）は references/ にあります。

• Python（デフォルト、アップロードなし）：一般的な CreateEvolveTask コマンドについては references/language-python.md §7 を、アルゴリズムプロジェクトの作成とアップロードについては references/algorithm-workflow.md を、ライフサイクル全体（開始／ポーリング／取得／停止）については references/evolve-task-workflow.md §3-§8 を参照してください。
• Python（OBS にアップロード）：上記と同じ内容に加え、1 回限りの agency／バケット認可については references/agency-policy.md を参照し、--output_path=obs://... を指定してください。
• C++（デフォルト、アップロードなし）：一般的な C++ の CreateEvolveTask コマンドについては references/language-cpp.md §5 を参照し、同じ evolve-task-workflow.md の参照先もご覧ください。

---

12. 関連ドキュメント

ドキュメント	目的
references/api-mapping.md	OptVerse／IAM から hcloud CLI へのマッピング
references/prerequisites.md	認証情報、環境、プロジェクト ID
references/parameter-format.md	パラメーター形式、ネスト、配列、JMESPath
references/iam-policies.md	IAM 権限ポリシー
references/iam-agency.md	IAM agency の作成／更新／削除
references/agency-policy.md	OBS バケット認可（agency 作成後）
references/language-python.md	Python プロジェクトの規約（評価器／ベースラインは同じファイル、2 つの実行モード）
references/language-cpp.md	C++ プロジェクトの規約（EVOLVE マーカー、build_command、コマンド形式の評価器）
references/algorithm-workflow.md	アルゴリズムプロジェクトのワークフロー
references/evolve-task-workflow.md	Evolve タスクのワークフロー
references/result-logs-status.md	結果、ログ、ステータス
references/troubleshooting.md	トラブルシューティング
references/verification-method.md	検証
references/plan-maintenance.md	（エージェント側、任意） plan／scratchpad ツールのメンテナンス（複数ステップのタスク状態マシン。エージェントにこれらのツールがない場合は省略してください）