| name | onescience-cli |
| description | 在远程 SSH/SLURM 环境中通过 `onescience` 命令执行任意 OneScience 子命令。根据命令级别（lightweight/normal/compute）自动选择执行通道。环境初始化由 `onescience-installer` 技能处理，计算节点申请与作业提交由 `onescience-runtime` 技能处理。本技能只负责 `onescience` 命令的调度与执行。 |
| type | executor |
OneScience CLI 技能
本技能根目录： 与当前 SKILL.md 同目录。资产路径均按本技能根目录解析，不按当前工作目录猜测。
需要环境检测与远程连接细则时，读取 ./references/cli_rules.md。
需要可渲染命令模板时，读取 ./references/cli_flow.md。
1. 职责与边界
本技能是在远端环境执行任意 onescience 命令的统一入口。onescience 命令需预先安装，本技能不检查或安装 onescience 工具。本技能不限制子命令范围，任何 onescience 支持的子命令均可透传执行。
负责：
- 执行
discover -> precheck（先检查计算节点 → 再检查环境）-> execute 运行闭环
- 根据命令级别（lightweight/normal/compute）自动选择执行通道
- 轻量命令（help/list/info/config）走快速通道，跳过环境探测与检查
- 消费
execution_mode、access_mode、execution_channel、hardware_profile
- 连接远端环境（参照
onescience-installer 的主机发现与连接方式）
- 环境检查：确认当前 shell 在计算节点上、环境已加载
- 调用
onescience 命令执行用户请求的子命令
- 返回执行结果与状态
不负责：
- 安装或修复 OneScience 完整环境（由
onescience-installer 负责）
- 安装或修复
onescience 工具
- 计算节点申请与 SLURM 作业提交（由
onescience-runtime 负责）
- 修改远端代码、配置或依赖
- 安装系统级组件或驱动
- 深度诊断训练/测试失败的业务原因
- 决定当前命令步骤之外的后续业务 executor 或全局工作流下一阶段
2. 固定阶段
| 阶段 | 触发条件 | 目标 | 关键输出 |
|---|
discover | 每次执行 | 命令级别判定 + 连接远端环境，收集运行目标与环境事实 | execution_mode、hardware_profile、remote_access_info、command_level |
precheck | 非 lightweight 级别 | 检查环境是否满足运行条件（先计算节点 → 再环境） | env_ready、on_compute_node、precheck_outcome |
execute | precheck 通过或 lightweight 快速通道 | 通过 onescience 命令执行用户请求的子命令 | onescience_command、execution_state、output |
三阶段按顺序推进，每阶段向用户实时汇报当前步骤。lightweight 级别跳过 precheck 直接进入 execute 快速通道。
precheck 发现不在计算节点时，交由 onescience-runtime 通过 sbatch 提交作业处理。precheck 发现环境未加载时，提示调用 onescience-installer。
CLI 只允许在当前命令步骤内进行这些显式委托：onescience-runtime 用于计算节点申请 / 提交 / 运行治理，onescience-installer 用于环境初始化。除这两类窄委托外，CLI 不得自行决定其他 downstream 业务技能；若后续问题超出 CLI 当前命令执行边界，必须返回 onescience-orchestrator 决策。
3. Discover 阶段
3.1 消费上游信息
优先消费：
skills/onescience-runtime/assets/execution_profiles.jsonskills/onescience-runtime/assets/backend_specs.json- 上游传递的
hardware_profile、execution_mode、access_mode
3.2 执行域判定
若上游未给出可靠 execution_mode，用 cli_flow.md 的 §0 判定当前 shell 是否已在目标环境中。
IN_CONTAINER=yes：视为 local_slurm，当前 shell 即为执行目标IN_CONTAINER=no：视为 remote_slurm，必须先完成主机发现
3.2a 命令级别判定
根据 cli_rules.md §0.1 规则判定当前命令级别：
| 级别 | 包含命令 |
|---|
lightweight | help, --version, list, info, config show/get |
normal | log, status, upgrade, remock, config set |
compute | bench 及所有训练/推理/评估命令 |
lightweight → 跳过 §1 环境探测和 §3 环境检查，走快速通道normal → 跳过 §1 环境探测和 §2 计算节点判定，执行 §3 环境检查compute → 执行完整三阶段
3.3 主机发现（remote_slurm）
参照 onescience-installer 的主机发现流程：
- 读取
onescience.json 的 runtime.remote
- 读取
~/.ssh/config
- 仍缺
user、host/hostname、port、identity_file 中任一项时，只询问缺失项
- 多个 Host 候选时，只询问选哪一个
Host 别名优先：当 ~/.ssh/config 中存在配置完整的 Host 条目时，使用 {ssh_host_alias} 替代完整的 -p -i user@host 参数。
3.4 §1 远端环境探测（硬件探测）
仅对 compute 级别执行：lightweight 和 normal 级别跳过本节。
执行命令：
remote_slurm：执行 cli_flow.md 的 §1local_slurm：执行 cli_flow.md 的 §1b
探测内容：
- NVIDIA GPU 检测（
nvidia-smi）
- AMD DCU 检测（
hipcc）
- 工具包目录检测（
/opt/dtk-*、/opt/rocm*、/usr/local/cuda*）
- 设备文件检测（
/dev/kfd）
- 模块环境检测（
module avail）
实时汇报：🔄 正在执行 §1 远端环境探测...
4. Precheck 阶段
命令级别决定跳过哪些检查步骤：
| 级别 | §2 计算节点判定 | §3 环境加载检查 |
|---|
lightweight | 跳过 | 跳过（走快速通道） |
normal | 跳过 | 执行 |
compute | 执行 | 执行 |
4.1 §2 计算节点判定（第一步）
仅对 compute 级别执行。
执行命令：
remote_slurm：执行 cli_flow.md 的 §2 远端判定local_slurm：执行 cli_flow.md 的 §2 就地判定
检查内容：
SLURM_NODEID：检查是否已设置SLURM_JOB_ID：检查是否已设置SLURM_JOB_NODELIST：检查是否已设置SLURM_NTASKS：检查是否已设置SLURM_CLUSTER_NAME：检查是否已设置hostname：获取当前主机名scontrol show node：尝试获取节点信息
实时汇报：📋 正在执行 §2 计算节点判定...
不在计算节点时：调用 onescience-runtime 技能，通过 sbatch 提交作业到计算节点执行。
4.2 §3 环境加载检查（第二步）
对 normal 和 compute 级别执行。
执行命令：
remote_slurm：执行 cli_flow.md 的 §3 远端检查local_slurm：执行 cli_flow.md 的 §3 就地检查
检查内容：
- Conda 环境列表：检查
onescience311 是否存在
- 当前激活环境：检查
$CONDA_DEFAULT_ENV 是否为 onescience311
- 已加载模块：检查
module list 输出
- OneScience 包：检查
python -c "import onescience; print(onescience.__version__)" 是否成功
实时汇报：📋 正在执行 §3 环境加载检查...
不满足条件时：调用 onescience-installer 技能完成环境初始化。
5. Execute 阶段
5.1 onescience 命令
命令形式为：
onescience {onescience_subcommand} {onescience_args}
其中 {onescience_subcommand} 是用户请求的子命令，{onescience_args} 是子命令后的附加参数。
5.2 模板选择
根据命令级别和执行模式选择模板：
| 级别 | remote_slurm | local_slurm |
|---|
| lightweight | §5 快速执行通道 | §5 就地 |
| normal | §6 普通执行命令 | §6 就地 |
| compute | §4 通用执行命令 | §7 通用执行命令 |
快速通道（lightweight）特点：
- 跳过环境探测、计算节点判定、环境加载检查
- 直接执行 onescience 命令
- 无需设置 WORLD_SIZE/MASTER_ADDR/MASTER_PORT 等环境变量
- 无需切换工作目录
普通通道（normal）特点：
- 跳过环境探测和计算节点判定
- 已确认环境就绪，直接执行
计算通道（compute）特点：
- 完整三阶段流程
- 需要确认在计算节点上
- 需要设置完整的训练环境变量
5.3 执行方式
remote_slurm：通过 SSH 在远端执行 onescience 命令
- lightweight：直接在远端执行（登录节点即可）
- normal：直接在远端执行（登录节点即可）
- compute：需在计算节点上执行；不在时通过
onescience-runtime 的 sbatch 提交作业
local_slurm：在当前计算节点上直接执行 onescience 命令
5.4 日志与输出管理
日志路径：
- 远端日志目录：
{remote_work_dir}/.onescience/cli_logs
- 远端输出目录：
{remote_work_dir}/.onescience/output
日志同步：
remote_slurm：执行完成后通过 scp 同步日志到本地 .onescience/cli_logs/local_slurm：直接复制到本地 .onescience/cli_logs/
输出展示：
- 执行日志路径（远端 + 本地）
- 输出文件列表
- 关键指标（如训练 loss、准确率等）
6. 用户交互
只在以下情况询问用户：
- 主机发现后仍缺 SSH 四元组中的字段
- 多个 Host 候选需要择一
- 不在计算节点上（compute 级别），建议交由
onescience-runtime 通过 sbatch 提交作业
- 环境未加载（env_not_ready），建议调用
onescience-installer
7. 最终输出
每次阶段汇报或执行完成时，直接向用户展示以下内容，无需用户再次询问：
快速通道输出（lightweight 级别）
🚀 快速通道：跳过环境探测与检查，直接执行
📋 目标主机：{hostname}
📋 命令级别：lightweight
🚀 execute：正在执行 onescience {onescience_subcommand} {onescience_args}...
📊 输出结果：
{output}
📊 执行状态：{execution_state}
📊 退出码：{exit_code}
标准通道输出（normal / compute 级别）
🔄 discover：正在连接远端环境...
📋 目标主机：{hostname}
📋 硬件类型：{required_backend_id}
📋 执行模式：{execution_mode}
🔄 precheck：正在检查环境...
📋 计算节点状态：{on_compute_node}
📋 环境加载状态：{env_ready}
🚀 execute：正在执行 onescience {onescience_subcommand} {onescience_args}...
📊 输出结果：
{output}
📊 执行状态：{execution_state}
📊 退出码：{exit_code}
📂 日志路径：{log_path}
失败时输出错误诊断
❌ 执行失败
📋 错误类型：{error_category}
📋 错误信息：{error_message}
📋 建议：{suggested_action}
📊 退出码：{exit_code}
错误类型说明
| 错误类型 | 说明 |
|---|
command_not_found | onescience 命令未找到 |
permission_denied | 权限不足 |
missing_config | 配置文件缺失 |
missing_data | 数据文件缺失 |
out_of_memory | 内存不足 |
network_error | 网络错误 |
cli_error | onescience 命令执行错误 |
ssh_failure | SSH 连接失败 |
8. 跨技能调用与验证
8.1 调用 onescience-installer 后的验证
验证流程：
- 等待
onescience-installer 返回 verify_state=verified
- 重新执行 §3 环境加载检查
- 确认
env_ready=true 后才进入 execute
- 若仍为
false，输出：
❌ 环境安装失败
📋 建议：手动检查环境或联系管理员
8.2 调用 onescience-runtime 后的状态跟踪
状态跟踪流程：
- 调用 runtime 提交 sbatch 作业
- 消费 runtime 返回的提交状态、日志引用与执行结果
- 若 runtime 返回的是继续等待 / 恢复当前命令步骤所需的信息，则在 CLI 当前命令上下文内继续完成展示
- 若 runtime 返回的阻断或下一动作已超出 CLI 当前命令边界，则返回
onescience-orchestrator 决策
CLI 不应在 runtime 已接管提交 / 状态 / 日志治理后，再自行扩展为 runtime 管理器（例如直接轮询 squeue 代替 runtime 的状态治理职责）。
9. 参考文件
| 文件 | 用途 |
|---|
./references/cli_flow.md | 可渲染命令模板（§0–§7） |
./references/cli_rules.md | discover / precheck / execute 细则，含命令分级、快速通道和 Host Key 容错 |
skills/onescience-installer/SKILL.md | 环境初始化委托给 onescience-installer 技能处理 |
skills/onescience-runtime/SKILL.md | 计算节点申请与作业提交委托给 onescience-runtime 技能处理 |
