# 环境踩坑档案（多机验证积累）

安装/排障前先扫这里。`setup_env` 脚本已内置规避 1-3。

## 1. 杀软拦 uv trampoline（Windows 企业机常见）

`uv venv` / `uv pip install` 报 `Failed to update Windows PE resources: ...uv-trampoline-*.exe 拒绝访问 (os error -2147024891)`。

根因：杀软/DLP 钩住 trampoline exe 的 PE 资源修改；换 TEMP 位置、`--link-mode=copy` 均无效。

规避：**标准库 venv + 纯 pip**——`<uv托管python> -m venv .venv && .venv/Scripts/python.exe -m pip install ...`（pip 的 distlib 脚本机制不受影响）。`uvx` 运行 MCP/工具正常（env 落 C 盘缓存）。

## 2. uvx 默认抓错系统 Python

机器上有专用工具链 python（如嵌入式 SDK 自带 3.8）时，`uvx <server>` 会用它解析依赖然后失败（`does not satisfy Python>=3.10`）。

规避：uvx 显式 `--python 3.12`。MCP 配置里已带。

## 3. mineru 3.4.5 漏声明 six

`mineru[pipeline]` 的 pytorchocr 模块 import six 但依赖里没有，首跑解析报 `No module named 'six'`。

规避：安装时显式加 `six>=1.16`（setup 脚本已带）。

## 4. MinerU 模型下载慢/失败

首次解析需下载模型（数百 MB~1GB+）。国内网络设 `MINERU_MODEL_SOURCE=modelscope`（脚本默认已设）；模型缓存于 `~/.cache/modelscope`。下载中断可重跑，续传。

## 5. MinerU 3.x CLI 参数与 2.x 不同

无 `-d/--device`；默认 backend 是 `hybrid-engine`（会拉大 VLM 模型）。CPU 场景必须显式 `-b pipeline`。`parse_paper.py` 已按 3.x 适配（双参数组兜底）。

## 6. Windows 临时目录跨盘

TEMP 在 C: 而仓库在 D: 时，跨盘 hardlink 警告无害；如遇安装异常可 `export UV_LINK_MODE=copy` 或把 TEMP 指到同盘。

## 7. obsidian vault 注册

装有 Obsidian 官方 CLI 时可命令行注册；否则在 Obsidian 里「打开文件夹作为仓库」一次即可（vault 本质是 markdown 目录，文件写入随时生效）。