| name | akg-env-setup |
| description | akg_agents 环境准备。缓存优先，检查 akg_cli + LLM 连通性， 未安装则引导安装，采集硬件/Framework/DSL。 FULL_SETUP 模式额外包含参数确认和运行时依赖安装。
|
| argument-hint | 可选：ENV_TYPE（conda/venv）、CONDA_ENV、VENV_PATH、AKG_AGENTS_DIR。 可选：FULL_SETUP=true（包含参数确认和运行时依赖安装，算子相关 agent 使用）。
|
akg_agents 环境准备
⛔ 核心规则
- 检查失败后只有两条路径：询问用户是否有其他可用环境、询问用户是否同意自动安装。除此之外禁止任何操作。
- 遇到 🛑 必须调用
question 工具并等待用户回复，不得跳过或自行决定。
- 禁止执行本文档未列出的命令。
流程总览
Step 0 解析 $HOME_DIR → 读取缓存
├─ 命中 ──────────────────────────────┬─ FULL_SETUP → Step 5
│ └─ 否则 → 结束
└─ 未命中 → Step 1 检查 akg_cli + LLM
├─ 通过 → Step 4 采集硬件/Framework/DSL
│ ├─ 4a 硬件
│ ├─ 4b Framework
│ ├─ 4c DSL & 后端推断
│ └─ 4d 写入缓存（必须，不可跳过）
│ ├─ FULL_SETUP → Step 5 → (Step 6 [可选，仅需要新依赖时]) → 结束
│ └─ 否则 → 结束
└─ 失败 → Step 2 询问用户（一次收集处理方式+环境信息）
├─ 已有环境 → Step 1（重试）
└─ 需要安装 → Step 3 → Step 1（重试）
Step 0: 解析 HOME_DIR & 读取环境缓存
首先执行以下命令获取 home 目录绝对路径，赋值给 $HOME_DIR：
echo $HOME
后续所有路径中的 $HOME_DIR 均使用此值。
然后读取 $HOME_DIR/.akg/check_env.md：
- 文件存在：
- FULL_SETUP → 跳到 Step 5（每次任务都需确认参数）
- 非 FULL_SETUP → 报告就绪，流程结束
- 文件不存在 → 进入 Step 1
Step 1: 执行两项检查
需要先确定 $ENV_TYPE、$CONDA_ENV/$VENV_PATH 和 $AKG_AGENTS_DIR。优先使用调用方提供的值，未提供时使用当前已激活的环境。
检查 1 — akg_cli 可用性：
conda:
conda run -n $CONDA_ENV --no-capture-output bash -c \
"cd $AKG_AGENTS_DIR && source env.sh && which akg_cli"
venv:
bash -c "source $VENV_PATH/bin/activate && cd $AKG_AGENTS_DIR && source env.sh && which akg_cli"
检查 2 — LLM 连通性：
conda:
conda run -n $CONDA_ENV --no-capture-output bash -c \
"cd $AKG_AGENTS_DIR && source env.sh && \
python tools/v2/use_llm_check/test_run_llm.py"
venv:
bash -c "source $VENV_PATH/bin/activate && cd $AKG_AGENTS_DIR && source env.sh && \
python tools/v2/use_llm_check/test_run_llm.py"
判定：
- ✅ 两项全部通过 → 进入 Step 4
- ❌ 任一失败 → 进入 Step 2，禁止自行尝试其他环境。
Step 2: 🛑 报告失败并询问用户
调用 question 工具，一次调用 3 个问题，同时收集处理方式和环境信息：
| # | header | question | options |
|---|
| 1 | 处理方式 | akg_agents 在当前环境中不可用。检查结果：<哪项通过、哪项失败及错误信息>。请选择处理方式： | "使用已有环境" / "新建环境安装" |
| 2 | 环境类型 | 选择 Python 环境类型 | "conda" / "venv" |
| 3 | 环境名或路径 | conda 填环境名（如 akg_agents），venv 填绝对路径（如 ~/akg/.venv） | "akg_agents（默认）" |
问题 3 用户可选择默认值或通过「自定义输入」填写自己的环境名/路径。
处理回复：
- 处理方式 = 使用已有环境 → 用问题 2、3 的回答设置
$ENV_TYPE、$CONDA_ENV/$VENV_PATH，回到 Step 1 重试
- 处理方式 = 新建环境安装 → 检测目标环境是否已存在：
- 不存在 → 进入 Step 3
- 已存在 → 再调用一次
question：
环境 $CONDA_ENV/$VENV_PATH 已存在，请选择：
- 复用该环境安装
- 删除重建
- 取消
- 复用 / 重建 → 进入 Step 3
- 取消 → 流程结束
Step 3: 委派 akg-installer
task(subagent_type="akg-installer", load_skills=[],
run_in_background=false,
description="Install akg_agents",
prompt="请安装 akg_agents。ENV_TYPE=<类型> CONDA_ENV=<名称>/VENV_PATH=<路径> ENV_ACTION=<reuse|recreate>。<用户原始请求>")
安装完成后，重新从 Step 1 开始检查（安装成功 → 检查通过 → 进入 Step 4）。
Step 4: 采集环境信息 & 写入缓存
Step 1 两项检查通过后执行以下步骤。
4a. 硬件采集（系统级，无需环境激活）
⛔ nvidia-smi 和 npu-smi info 的输出禁止截断（不得添加 head/tail/| head -N 等），必须获取完整输出以准确识别所有设备数量。截断会导致多卡被误认为少卡。
uname -m
cat /proc/cpuinfo 2>/dev/null | grep "model name" | head -1 || sysctl -n machdep.cpu.brand_string 2>/dev/null
nvidia-smi 2>/dev/null
npu-smi info 2>/dev/null
free -h 2>/dev/null || sysctl hw.memsize 2>/dev/null
采集后处理：从工具输出中提取芯片型号后，必须按规范化规则转换再写入缓存。例如 npu-smi 输出的 910B4 必须转换为 ascend910b4，nvidia-smi 输出的 A100 必须转换为 a100。缓存中的 arch 字段必须是规范化后的值。
4b. Framework 采集（在环境中执行）
torch 始终采集。torch_npu 仅在 4a 检测到 Ascend NPU 时采集。
| 项目 | 采集条件 | <CMD> |
|---|
| torch | 始终 | python -c "import torch; print(torch.__version__, 'CUDA:', torch.cuda.is_available())" |
| torch_npu | 有 Ascend NPU | python -c "import torch_npu; print(torch_npu.__version__)" |
4c. DSL 采集 & 后端推断
triton 仅在 4a 检测到 Ascend NPU 或 NVIDIA GPU 时采集：
| 项目 | <CMD> |
|---|
| triton | python -c "import triton; print(triton.__version__)" |
| g++/clang++ | g++ --version 2>/dev/null || clang++ --version 2>/dev/null（系统命令，无需命令模板） |
按检测结果列出所有可用后端（一台机器可匹配多行）：
| 条件 | 后端 | DSL | 架构 |
|---|
| Ascend NPU + torch_npu + triton | ascend | triton_ascend | 从 npu-smi 解析型号 |
| NVIDIA GPU + CUDA + triton | cuda | triton_cuda | 从 nvidia-smi 解析型号 |
| g++/clang++ 可用 | cpu | cpp | uname -m |
⛔ 4d. 写入 $HOME_DIR/.akg/check_env.md
**重要：**此步骤不可跳过。不写入缓存，后续每次启动都会重复完整环境检查。
将 Step 4a–4c 的采集结果按附录格式写入 $HOME_DIR/.akg/check_env.md。环境缓存示例：@references/example_check_env.md
写入后立即验证：
test -f $HOME/.akg/check_env.md && echo "✅ 缓存已写入" || echo "❌ 缓存写入失败"
验证通过后：
- 非 FULL_SETUP → 报告环境就绪，流程结束
- FULL_SETUP → 进入 Step 5
Step 5: 🛑 参数推断与确认（FULL_SETUP 模式）
从 $HOME_DIR/.akg/check_env.md 的「可用后端 & DSL & 架构」表中读取所有可用组合，用 question 工具请用户选择本次使用的配置：
根据您的环境检测，可用配置如下：
请选择：
- backend=cuda, arch=a100, framework=torch, dsl=triton_cuda
- backend=cpu, arch=x86_64, framework=torch, dsl=cpp
...
options 只列出缓存中检测到的组合，不要添加"自行输入"类选项（question 工具自带「Type your own answer」入口，用户需要自定义时会自行使用）。缓存中只有一行时也需确认。
确认后按「算子参数规范化」规则处理（小写、别名转换、连字符→下划线等）。
进入 Step 6。
Step 6: 运行时依赖安装（FULL_SETUP 模式）
如果用户在 Step 5 选择的配置来自 check_env.md 中已有的组合，说明依赖已就绪，跳过本步骤，直接报告环境就绪并返回参数。
仅当用户通过「Type your own answer」输入了 check_env.md 中不存在的配置时，才需要检测并安装缺失依赖（所有 pip 命令通过命令模板在环境中执行）：
backend = cpu
| 缺失 | 处理 |
|---|
| torch | pip install torch --index-url https://download.pytorch.org/whl/cpu |
| g++/clang++ | 检查可用性，不可用告知用户 |
backend = cuda
| 缺失 | 处理 |
|---|
| torch | pip install torch |
| triton | pip install triton |
backend = ascend
| 缺失 | aarch64 | x86_64 |
|---|
| torch | pip install cpu 版 | 🛑 需用户提供 .whl |
| torch_npu | pip install | 🛑 需用户提供 .whl |
| triton-ascend | 🛑 需用户提供 .whl | 🛑 需用户提供 .whl |
🛑 标记项必须调用 question 工具索要 .whl 路径。
pip 包名用连字符（如 triton-ascend），API 参数用下划线（如 triton_ascend）。
**【重要】：**安装完成后，更新 $HOME_DIR/.akg/check_env.md，重新执行 Step 4b–4c 采集最新 Framework 和 DSL 版本。
报告环境就绪，向调用方返回已确认的 framework/backend/arch/dsl。流程结束。
附录：$HOME_DIR/.akg/check_env.md 完整格式
# AKG Agents 环境缓存
> 自动生成。删除此文件可强制重新检查。
## 环境配置
- HOME_DIR: <绝对路径>
- ENV_TYPE: <conda 或 venv>
- CONDA_ENV: <环境名>（仅 conda）
- VENV_PATH: <路径>（仅 venv）
- AKG_AGENTS_DIR: <绝对路径>
## 命令模板
将 <CMD> 替换为实际命令：
<根据 ENV_TYPE 和 AKG_AGENTS_DIR 生成的完整命令模板，含激活环境和 source env.sh>
## 验证状态
- akg_cli: ✅
- LLM: ✅ 或 ⚠️（未配置 API Key）
## 硬件
- CPU: <架构和型号>
- GPU/NPU: <型号或无>
- 内存: <大小>
## Framework
- torch: <版本> (CUDA: True/False)
- torch_npu: <版本>（如有）
## DSL
- triton: <版本>（如有）
- g++/clang++: <版本或"未安装">
## 可用后端 & DSL & 架构（可多行）
| 后端 | DSL | 架构 |
|------|-----|------|
| <后端1> | <DSL1> | <架构1> |
| <后端2> | <DSL2> | <架构2> |
环境缓存仅存储环境级信息（硬件、已安装的 Framework和DSL、命令模板）。任务级参数配置（framework/backend/arch/dsl 选择、当次所用的 device id等）不缓存，每次任务由调用方确认。
