搜“SkillOpt 怎么安装”时，最容易踩的坑不是命令拼错，而是把 PyPI 安装和源码安装当成一回事。前者适合直接拿到三个命令行工具，后者才包含论文复现需要的配置、数据准备脚本、Agent 集成外壳和开发测试。先确定你要“用工具”，还是要“跑完整研究流程”，安装路径自然就清楚了。

只想先看看命令能不能跑，装哪个版本？

准备 Python 3.10 或更高版本。只用正式发布的命令行工具时，直接安装 PyPI 包：

python -m pip install skillopt
skillopt-train --help
skillopt-eval --help
skillopt-sleep --help

成功标志不是“pip 没报错”这么简单。三个帮助命令都应能打印参数说明，下面的导入检查也应输出 SkillOpt ready!：

python -c "import skillopt; print('SkillOpt ready!')"

当前官方 PyPI 版本是 0.2.0。若文档里出现 main 分支才有的新后端、Sleep handoff、非 Azure 的 OpenAI-compatible Sleep 接口或 Cursor 支持，PyPI 版本可能还没有；这时再切到源码安装。

要跑示例、改配置，源码装法更省事

把仓库克隆到独立目录，不要混进现有业务项目的虚拟环境。官方给出的 HTTPS 路径是：

git clone https://github.com/microsoft/SkillOpt.git
cd SkillOpt
python -m pip install -e .

这里的 -e 会把当前源码目录作为可编辑安装。以后拉取更新或修改代码，不必反复复制包文件。需要特定能力时再加 extras，例如 WebUI 使用 python -m pip install -e ".[webui]"，SearchQA 数据准备使用 python -m pip install -e ".[searchqa]"。

为什么装完却找不到官方配置？

现象通常是命令可用，但找不到 configs/searchqa/default.yaml 或插件目录。原因是你装的是 PyPI wheel，它本来就不带基准配置、数据物化脚本和集成外壳。补救不是重装同一个 wheel，而是克隆官方仓库并执行可编辑安装。

模型凭据该放哪里，哪些情况根本不需要？

研究训练需要至少一个可用模型后端；Sleep 的 mock 后端不需要凭据。源码目录提供 .env.example，可复制为 .env，但 SkillOpt 不会自动加载它，运行前还要把变量导出到当前 shell。

cp .env.example .env
set -a
source .env
set +a

Azure OpenAI、OpenAI-compatible、Claude CLI、Qwen 等后端使用的变量不同，只配置你实际选择的那一组。密钥不要写进示例 Skill、训练输出或文章代码块，也不要提交到 Git。

环境变量明明写了，训练仍说后端不可用

常见现象是新终端里变量消失，或模型名与 YAML 里的角色配置冲突。触发原因通常是只编辑了 .env 却没有 source，或者 model.optimizer、model.target 覆盖了环境变量。修复时先在同一终端重新导出变量，再检查当前 YAML 的两个角色模型。

第一次试跑别从“大规模训练”开始

官方最短演示使用 SearchQA。源码仓库只带稳定 ID 清单，需要先安装数据 extra，再物化训练、验证和测试拆分：

python -m pip install -e ".[searchqa]"
python scripts/materialize_searchqa.py
python scripts/train.py 
  --config configs/searchqa/default.yaml 
  --out_root outputs/searchqa_first_run

训练开始后会打印解析后的后端、数据配置、每一步 rollout 与 gate 进度。可见结果写进 outputs/searchqa_first_run/：其中 best_skill.md 是当前最优技能，steps/ 保存候选和轨迹摘要，slow_update/ 与 meta_skill/ 保存跨 epoch 信息。

命令启动了，却一直没有可用的 best_skill.md

先看终端是否停在数据、鉴权或模型调用阶段。数据目录缺失时重新物化 SearchQA；鉴权失败时核对所选后端；候选反复被拒绝则查看 gate 分数，而不是删除验证门。best_skill.md 只有在训练目录正确创建并出现可保留版本后才有意义。

哪些人适合直接上手，哪些人应该先停一下？

已有可评分任务集、能承担模型调用成本、愿意把训练集与选择集分开的团队，适合从小规模实验开始。只有几条零散对话、没有稳定判定标准，或准备把敏感会话直接交给第三方后端的项目，不适合急着跑完整训练。先整理任务和数据边界，比盲目调 learning rate 更重要。

检查节点	看到什么才算完成
Python	版本不低于 3.10
命令	train、eval、sleep 的帮助页均能打开
源码	仓库内能看到 configs、scripts、docs
后端	当前 shell 已导出所选后端需要的变量
试跑	输出目录出现配置、步骤记录和 best_skill.md

企业内部真正落地时，最好让一个人负责数据与评分，一个人复核技能变化，再由使用团队决定是否部署 best_skill.md。安装只是把工具摆上工作台；能不能把验证样本守住，才决定后面的训练结果值不值得采用。