huawei-cloud-optv-evolve-management

⚠️ 执行方式（必读）：所有脚本都必须通过 skill action=exec 执行；不要直接在 shell 中运行。

• 此技能中的所有 OptVerse 调用都必须通过 KooCLI（命令行入口 hcloud）进行。禁止使用 requests 或任何其他 HTTP 库直接调用 OptVerse OpenAPI。
• scripts/ 中的文件是随技能提供的辅助工具（zip_helper.py / cache.py）；它们都是纯本地工具，不会调用 KooCLI 子进程。
• Agent 本身不得创建一次性临时 .py 脚本文件；处理 Python JSON 时，优先使用 python -c "..." 内联执行。 不要创建临时脚本文件（.py / .sh 等）；临时产物（zip 包、JSON 缓存、扫描结果）应放在固定位置的 .stats/ 或 OPTV_CACHE_DIR 中，使用后必须清理。 ⚠️ 安全规则（必读）：切勿在对话、脚本或输出中泄露 AK / SK。只能通过 hcloud configure list 验证凭证是否存在。

算法自动设计技能（英文）

概述

在华为云科学计算专区 — 算法设计模块中进行端到端代码演进：

• 将算法代码、评估器和基线上传到算法设计项目
• 创建并启动演进任务、监控进度、获取结果和日志

需要将结果上传到 OBS 桶时（可选路径，默认场景可跳过）：

• 创建 / 维护 IAM Agency，作为跨服务信任锚点
• 向算法设计模块授予桶（OBS）权限

支持的语言：

语言	算法	evaluator	baseline
Python	源文件 + 函数名	含有 def evaluate(): 的源文件（例如 evaluator.py）	含有 def baseline(): 的源文件（例如 baseline.py）
C++	源文件 + 函数名（演进函数）	已编译的可执行命令（例如 build/evaluate <args>）	已编译的可执行命令（可以与 evaluator 相同）

C++ 项目使用 CreateAlgorithm --build_command 将上传的 .cpp 文件编译为可执行文件。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（按用途划分的三个子目录）：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）。预检查涵盖：① KooCLI 安装 ② AK/SK 配置 ③ 区域配置 ④ OptVerse API 连通性。

1.0 一次性环境检查（必需的第一步）

⚠️ Windows Shell 选择：使用 powershell（系统预装的 Windows PowerShell 5.1；此技能已验证 PS 5.1 + precheck.ps1 通过全部 5 项检查）。 默认情况下，在 Windows 上避免使用 bash：where bash 可能会解析到 C:\Users\<user>\AppData\Local\Microsoft\WindowsApps\bash.exe（一个 WSL 启动器存根；若未安装 WSL，会卡在“install WSL”提示上）；此技能未验证 WSL bash。

开始任务前，必须通过 skill action=exec 调用一次预检查脚本（一次完成 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 子章节的对应关系）：

预检查项	对应章节
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 委托 + 存储桶授权（前提条件：连通性正常）

不在检查范围内的内容（需单独验证）：

• §1.3 Python 解释器（预检查不会探测 python）
• §1.4 IAM 权限（预检查不会验证 IAM 操作权限）
• §1.5 创建委托 + 存储桶授权（预检查仅验证连通性，不会实际创建委托 / 授权存储桶）

1.0.1 备用 Shell 表

如果无法使用 powershell，唯一有文档说明的备用 Shell 是 bash（Git Bash / MSYS2 / Linux）。此技能未验证 WSL bash——请避免使用。

探测项	含义	建议的预检查命令
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（在非交互式脚本中通过管道输入 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。必须通过 skill action=exec argv 数组形式调用 hcloud；切勿通过 powershell_exec hcloud ... 调用。在 KooCLI 子进程中展开 PowerShell 变量（$AID / $TID）可能会悄无声息地破坏参数值，并导致令人困惑的“invalid parameter value”错误。

1.4 IAM 权限

所需操作列于 references/iam-policies.md。系统策略 OptVerse FullAccess + Security Administrator 可用于健全性检查；生产环境应使用该文件中的自定义策略 JSON。

1.5 委托 + 存储桶授权（可选）

如果进化任务需要将结果上传到您自己的 OBS 存储桶，必须先创建 IAM 委托，再授权该存储桶。如果不需要上传结果（只需通过 OptVerse 控制台 / hcloud 检查进度和结果），则可跳过这两个步骤；此时 CreateEvolveTask --output_path 留空。

可视化流程和具体命令见 §4.2 §A“首次准备”。详细操作见 references/iam-agency.md 和 references/agency-policy.md。

如何判断：如果您只想在 OptVerse 控制台或通过 hcloud 查看进化结果，且不需要在 OBS 中保存产物，则可以跳过 §A，并使用 §B.2 的 --output_path=""。

---

2. 触发条件

出现以下任一用户意图时，启用此技能：

• “创建进化任务” / “启动进化任务” / “停止/删除进化任务”
• “上传算法代码” / “向算法项目添加评估器”

---

3. 安全与风险约束

• 每次破坏性调用都必须进行两步确认：打印命令和风险警告；只有在用户明确确认后才能执行。适用于 IAM DeleteAgency、OptVerse DeleteAlgorithm、OptVerse DeleteEvolveTask、OptVerse BatchDeleteEvolveTask、OptVerse RevokePermission。
• 绝不重命名已上传的文件；传给 --file_path 的文件路径必须等于 os.path.basename(local_file)。
• 基于时间的效率函数必须使用并发数 = 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 格式

平台提供了三个官方示例算法，供参考和临时调试：

algorithm_id	算法
0	排序
1	CVRP
2	CirclePacking

两种 algorithm_id 格式并存：

• 官方示例：较短的数字字符串 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）依赖 shell 拆分令牌，这在不同平台 / 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 仅在检测到图形桌面时打开浏览器；在无头 / SSH 无 X11 / 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 可执行文件必须向 stdout 输出单个浮点数，并以换行符结尾。

经实测验证：evaluator_file 和 evaluator_baseline 可以是同一个文件（函数名必须不同）。

必填字段的 3 层分类（Agent 在调用 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 是大模型提示词

请按提示词的形式编写：

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 破坏性调用需分两步确认

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 数组形式（避免 shell 转义问题和跨 shell 不可靠）
3. 必须使用 --key=value 形式，绝不能使用 --key value 空格分隔形式

不同的 Agent / Skill Runtime 使用不同的“调用形式”语法；下表按优先级排列：

风格组合（调用风格 + 路径方案）	调用示例	说明
Skill Runtime 封装器 + Skill URI（首选）	skill action=exec --name <skill> --command ["powershell","-File","skill://scripts/precheck.ps1"]	Skill Runtime 会自动将 skill:// 解析为 skill 包根目录；跨 shell 稳定
Skill Runtime 封装器 + 绝对路径（备用）	skill action=exec --name <skill> --command ["powershell","-File","/abs/path/scripts/precheck.ps1"]	适用于 Skill Runtime 不支持 skill:// 的情况
直接使用 shell + 相对路径（cwd 必须位于 skill 根目录）	powershell scripts/precheck.ps1	直接调用 bash / PowerShell 工具；要求 cwd 已位于工作区
直接使用 Python fork（不推荐）	python -c "import subprocess; subprocess.run(['hcloud',...])"	绕过 Agent 框架的隔离 / 缓存语义

⚠️ 可用的风格取决于你的 Agent 框架（请参阅其文档）。无论使用哪种风格，都必须遵守 3 条铁律。

反模式（任何风格下均禁止）

❌ 反模式	问题所在
requests.post('https://optverse...', json=...) 直接调用 OpenAPI	绕过 KooCLI 身份验证 / 错误处理 / 重试 / --debug 日志记录；触碰“直接调用 OpenAPI”红线
--key value 空格分隔形式	bash 会将其拆分为 --key=（空值）+ value（独立标记）；PowerShell $VAR 不会展开
python -c "import subprocess; ..." 自行 fork hcloud	绕过 Agent 框架的隔离 / 缓存语义；与 Skill Runtime 的脚本调用机制不一致

轮询策略

在 CreateEvolveTask（含）之前，Agent 必须询问用户从两种轮询模式中选择一种；不要等到 CreateEvolveTask / StartEvolveTask 之后再询问——这会打乱流程，且 Agent 会在 StartEvolveTask 后立即陷入轮询循环。

• (a) Agent 主动轮询：循环调用 ShowTaskDetails，直到状态为 FINISHED / FAILED / STOPPED
• (b) 用户自行查询（推荐）：将 evolve_task_id 和直接链接（python skill://scripts/build_task_url.py -r <region> --task-id <tid> --open）交给用户；之后按需查询 ShowTaskDetails。

不推荐一开始就启动轮询（避免长时间占用 Agent 会话）

---

7. 文件系统约定

7.1 临时文件

• 绝不要在 skill 目录或用户主目录中写入临时文件。
• 自动生成的临时脚本必须放在 OPTV_CACHE_DIR 下（默认为 skill 的 .stats/ 文件夹），并在之后清理。

7.2 缓存文件

.stats/ 由人工维护：

• .stats/algorithm_id.csv — 当前启用的算法 ID
• .stats/task_id.csv — 本会话创建的每个 evolve 任务

7.3 文件名一致性

⚠️ 请勿重命名上传的文件。 Python evaluator / baseline 的文件名不作严格要求——重要的只是 CreateEvolveTask 中传给 --evaluator_file / --evaluator_baseline 的文件（平台会按文件名导入）。对于 C++ 项目，build_command 必须编译出名称与 --evaluator_func_name / --evaluator_baseline_func_name 匹配的可执行文件。

8. 参数类别快速参考

参数语法参考：详细的 --key=value / 嵌套 / 数组 / 枚举 / 大小限制 / JMESPath 语法请参阅 references/parameter-format.md。本节仅供 Agent 快速进行 A/B/C 分类。

开始任务时，Agent 按照以下三个类别确定每个参数的来源——先填写 A，再收集 B，最后用 C 中的默认值补全。

8.1 A. 预配置（Agent 自动获取，不要询问用户）

参数	来源
--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	Agent 运行 hcloud OptVerse ShowAlgorithm 获取 content_update_at，然后运行 scripts/cache.py put-lut --lut <ms> 写入；后续调用时使用 get-lut 读取

8.2 B. 必须询问用户（Agent 不得猜测）

开始前一次性收集全部信息，不要逐步询问：

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. 启动后的轮询模式（必填）：选择一种，参见 §6.8 跨平台调用原则；长任务优先让用户自行查询
10. 破坏性操作的两步确认——参见 §3

8.3 C. Agent 自动生成（用户可覆盖；不要主动询问）

参数	默认规则
--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 封装了缓存文件的读写操作。运行命令前，Agent 会使用 $(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 流程都由 Agent 在 shell 中编排；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 通常会列出 build / build/，以排除 cmake 构建产物。如果没有 .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（默认，不上传）：请参阅 references/language-python.md §7，了解典型的 CreateEvolveTask 命令；参阅 references/algorithm-workflow.md，了解算法项目的创建与上传；参阅 references/evolve-task-workflow.md §3-§8，了解完整生命周期（启动 / 轮询 / 获取 / 停止）。
• Python（上传到 OBS）：同上，并参阅 references/agency-policy.md，了解一次性 agency / 存储桶授权，以及 --output_path=obs://...。
• C++（默认，不上传）：请参阅 references/language-cpp.md §5，了解典型的 C++ CreateEvolveTask 命令，以及相同的 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 项目约定（评估器 / 基线位于同一文件，两种运行模式）
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	（Agent 侧，可选） plan / scratchpad 工具维护（多步骤任务状态机；如果你的 Agent 没有这些工具，则跳过）