# 研究环境使用说明

## 激活

在项目根目录的 PowerShell 中运行：

```powershell
. .\research\environment\activate-research.ps1
```

该脚本会激活 `.venv-research`，设置项目内 R、R library、CUDA 13.4，并把 uv、renv、PyTensor、Numba、Matplotlib、Skrub、Hugging Face 与 Torch 缓存定向到项目目录。

## 验收

```powershell
python .\research\environment\smoke_test.py
Rscript .\research\environment\r-smoke-test.R
cmd.exe /d /c .\research\environment\cuda-smoke-build.cmd
```

期望结果：Python JSON 中所有 imports/tests 为 `passed`；R JSON 中所有 imports/tests 为 `passed` 且 mirt `converged=true`；CUDA 输出 `cuda_smoke_result=42`。

## Python 恢复

Python 版本固定为 3.12 系列，完整包版本见 `python-requirements.lock.txt`。Torch 使用 PyTorch 官方 CUDA 13.0 索引：

```powershell
uv python install 3.12 --install-dir .python --no-registry --no-bin --cache-dir .uv-cache
uv venv .venv-research --python .python\cpython-3.12.14-windows-x86_64-none\python.exe --seed --no-project --cache-dir .uv-cache
uv pip install --python .venv-research\Scripts\python.exe --requirements research\environment\python-requirements.lock.txt --index https://download.pytorch.org/whl/cu130 --index-strategy unsafe-best-match --cache-dir .uv-cache
```

若 3.12 补丁版本更新，第二条命令应使用实际安装目录，不要硬编码旧补丁版本。

## R 恢复

R 版本为 4.6.1。顶层包安装入口为 `install-r-packages.R`；完整依赖恢复使用 `renv.lock`。先激活环境，再运行：

```powershell
Rscript -e "renv::restore(lockfile='research/environment/renv.lock', library='.r-library/4.6', prompt=FALSE)"
```

## 约束

- 正式分析只使用上述项目环境；不要把系统 Python 3.13 的包状态当作项目依赖。
- `smoke-test-result.json` 的短链 PyMC 采样只用于环境验收。
- `cuda-smoke.exe` 是可重建产物；源码和构建脚本才是复现入口。
- 嵌入模型权重尚未冻结，下载前仍须执行模型许可与版本审计。