msModeling 环境安装器

适用场景

直接使用本 skill 的场景：

• 用户明确要求安装 msmodeling 环境依赖、初始化 msmodeling 开发环境或按 msmodeling README 配置环境。
• 用户明确要求在当前 msmodeling 仓库中创建 myenv。
• 用户明确要求安装当前仓库的 requirements.txt。
• 用户明确要求检查当前 msmodeling Python 依赖。
• 用户明确要求为当前 msmodeling 会话配置 PYTHONPATH。
• 用户明确要求配置 Hugging Face 镜像 HF_ENDPOINT=https://hf-mirror.com。
• 用户已有 Python 环境，并明确希望为 msmodeling 执行 fallback 依赖安装。

需要先确认的场景：

• 用户只说“安装环境”“安装依赖”“配置环境”“初始化环境”，但没有明确说明是 msmodeling、本仓库、requirements.txt、myenv 或 uv。
• 当前仓库后续可能存在其他环境安装工具时，不能默认选择本 skill。

遇到上述模糊请求时，先向用户确认：

你是要安装 msmodeling 当前仓库的环境依赖吗？确认后我会使用 msmodeling-env-installer 执行。

只有用户确认后，才继续执行本 skill 的安装流程。

默认策略

优先使用 README 推荐的 uv 流程创建独立虚拟环境，并在安装后执行依赖一致性检查。

默认值和约束：

• 默认虚拟环境名为 myenv。
• Python 最低版本为 3.10。
• 默认使用当前机器检测到的 Python 主次版本创建虚拟环境，避免 uv 额外下载 Python；只有用户显式要求或本机不可用时才使用 README 示例中的 3.13。
• 默认使用中科大 PyPI 镜像：https://mirrors.ustc.edu.cn/pypi/web/simple。
• 默认不覆盖已有环境；如果 myenv 已存在，需说明复用或重建的影响。
• 默认不持久化系统环境变量，只设置当前 shell 会话或给出可执行命令。
• 涉及网络安装时，先展示将执行的命令，并按当前工具权限请求用户授权。

环境选择策略

根据当前运行环境选择自动化脚本：

当前环境	优先命令
Windows PowerShell	.\\skills\\msmodeling-env-installer\\scripts\\install-current-project-deps.ps1
Linux/macOS Bash	bash ./skills/modeling/msmodeling-env-installer/scripts/install-current-project-deps.sh
WSL/Git Bash	bash ./skills/modeling/msmodeling-env-installer/scripts/install-current-project-deps.sh

如果当前 shell 与操作系统不匹配，优先选择当前 shell 可直接执行的脚本。例如在 Windows 的 Git Bash 中使用 .sh，在 Windows PowerShell 中使用 .ps1。

工作流程

1. 确认用户意图明确指向 msmodeling 环境依赖；如果只是泛化的“安装环境”，先询问是否安装 msmodeling 当前仓库的环境依赖。
2. 检查当前目录是否为 msmodeling 仓库根目录，至少包含 README.md 和 requirements.txt。
   • 若当前目录不是 msmodeling 仓库根目录，先检查当前目录下是否已有 msmodeling/README.md 和 msmodeling/requirements.txt；若存在，进入 msmodeling 后继续。
   • 若当前目录及其下级 msmodeling/ 都不存在仓库，说明将创建 msmodeling 目录并从官方仓库克隆；获得授权后直接执行：

     git clone https://gitcode.com/Ascend/msmodeling.git
     cd msmodeling
     

   • 克隆后必须重新确认 README.md 和 requirements.txt 存在，再继续环境安装。
3. 检测 python、python3 或 Windows py -3，确认 Python 版本为 3.10+。
4. 检查 uv 是否可用；缺失时用 python -m pip install uv -i https://mirrors.ustc.edu.cn/pypi/web/simple 安装。
5. 安装或调用 uv 后，解析真实 uv 可执行路径，不能假设当前 shell 的 PATH 已刷新。
6. 选择安装路径：
   • 新建 myenv：使用 uv venv --python <detected-python-version> myenv。
   • 已有环境 fallback：先检查当前环境不包含 torch_npu、torch-npu、cudatoolkit，再执行 pip install -r requirements.txt。
7. 安装依赖：优先执行 uv pip install --python <venv-python> -r requirements.txt -i <mirror>。
8. 按需设置当前会话环境变量：
   • PYTHONPATH 指向 msmodeling 仓库根目录。
   • HF_ENDPOINT 设置为 https://hf-mirror.com。
9. 执行依赖检查：
   • uv pip check --python <venv-python>。
   • 已有环境 fallback 使用 python -m pip check。
10. 向用户报告激活命令、安装结果、验证结果和后续建议。

命令模板

新建环境

pip install uv -i https://mirrors.ustc.edu.cn/pypi/web/simple
uv venv --python <detected-python-version> myenv
uv pip install --python <venv-python> -r requirements.txt -i https://mirrors.ustc.edu.cn/pypi/web/simple

激活命令：

操作系统	命令
Linux/macOS/WSL/Git Bash	source myenv/bin/activate
Windows PowerShell	myenv\Scripts\Activate.ps1
Windows cmd	myenv\Scripts\activate.bat

已有环境 fallback

使用该路径前必须先检查当前环境：

python -c "import importlib.util, sys; sys.exit(0 if importlib.util.find_spec('torch_npu') else 1)"
python -m pip show torch-npu
python -m pip show torch_npu
python -m pip show cudatoolkit

如果任一检查显示包存在，不要默认继续 fallback。建议用户新建 myenv，或让用户明确确认继续使用该环境。

python -m pip install -r requirements.txt
python -m pip check

环境变量

Linux/macOS/WSL/Git Bash：

export PYTHONPATH="$(pwd):${PYTHONPATH:-}"
export HF_ENDPOINT="https://hf-mirror.com"

Windows PowerShell：

$env:PYTHONPATH = "$(Get-Location);$env:PYTHONPATH"
$env:HF_ENDPOINT = "https://hf-mirror.com"

自动化脚本

仓库内脚本：

脚本	适用环境
scripts/install-current-project-deps.ps1	Windows PowerShell
scripts/install-current-project-deps.sh	Linux/macOS/WSL/Git Bash

脚本会先确认当前目录是否为 msmodeling 仓库根目录；如果当前目录下已有 msmodeling/ 仓库则自动进入；如果两者都不存在，则按 optix-deploy 的方式从 https://gitcode.com/Ascend/msmodeling.git 克隆后再继续安装。

PowerShell 参数：

参数	说明
-EnvName	虚拟环境目录名，默认 myenv
-PythonVersion	uv venv 使用的 Python 版本，默认使用检测到的本机 Python 主次版本
-UseExistingEnv	跳过新建 venv，使用已有环境安装依赖
-SetProjectEnv	为当前 PowerShell 会话设置 PYTHONPATH
-UseHFMirror	为当前 PowerShell 会话设置 HF_ENDPOINT
-UseProjectUvCache	默认启用，将 UV_CACHE_DIR 指向仓库内 .uv-cache

Bash 参数：

参数	说明
--env-name <name>	虚拟环境目录名，默认 myenv
--python-version <version>	uv venv 使用的 Python 版本，默认使用检测到的本机 Python 主次版本
--use-existing-env	跳过新建 venv，使用已有环境安装依赖
--set-project-env	输出并为当前脚本进程设置 PYTHONPATH
--use-hf-mirror	输出并为当前脚本进程设置 HF_ENDPOINT
--no-project-uv-cache	不设置仓库内 .uv-cache 作为 UV_CACHE_DIR

示例：

.\skills\modeling\msmodeling-env-installer\scripts\install-current-project-deps.ps1
.\skills\modeling\msmodeling-env-installer\scripts\install-current-project-deps.ps1 -SetProjectEnv -UseHFMirror
.\skills\modeling\msmodeling-env-installer\scripts\install-current-project-deps.ps1 -UseExistingEnv

bash ./skills/modeling/msmodeling-env-installer/scripts/install-current-project-deps.sh
bash ./skills/modeling/msmodeling-env-installer/scripts/install-current-project-deps.sh --set-project-env --use-hf-mirror
bash ./skills/modeling/msmodeling-env-installer/scripts/install-current-project-deps.sh --use-existing-env

安全规则

• 不修改 requirements.txt、README 或项目源码。
• 不在未经确认时执行网络安装、删除环境或覆盖已有虚拟环境。
• 用户请求不明确时，不默认执行 msmodeling 环境安装，必须先确认。
• 不默认持久化系统级环境变量。
• fallback 安装前必须检查 torch_npu、torch-npu 和 cudatoolkit。
• Windows 下如遇 PyTorch 兼容问题，提醒用户 README 中的 Windows PyTorch 版本风险；未安装 PyTorch 时优先建议 2.8 或更早版本。
• 失败时保留完整命令、关键错误、失败阶段和最小修复建议。

完成标准

• 用户意图已确认指向 msmodeling 环境依赖。
• 仓库根目录、Python 版本、uv 可用性检查完成。
• 依赖安装流程完成，或失败原因已明确分类。
• pip check 或 uv pip check --python <venv-python> 已执行并报告结果。
• 输出用户后续可直接执行的激活命令。
• 明确说明当前会话是否设置了 PYTHONPATH 或 HF_ENDPOINT。