setup

首次配置 — 环境初始化指南

Task

用户通常使用 Mac 处理历史文献扫描件（繁体古籍、民国排印本、现代简体论文），并非都具备技术背景。本 skill 的目标是在一次会话内完成三件事：

1. 建立本插件的 Python 运行环境（3.9+，opencv、pillow、poppler 等依赖）
2. 预装并预热 MinerU 本地 CLI（默认路径）；或按需启用百度 OCR / MinerU 云 API 兼容分支
3. 通过一次探活确认引擎可用

任一步失败时必须显性终止，不要跳过或静默兜底。

Process

Step 1：确认用户环境

首先确认：

• 用户是否用过命令行 / 终端？不熟悉终端的用户需要逐条解释命令含义。
• 默认走本地 MinerU CLI（无需账号、不上传、首次装机约 10 分钟、之后每份 PDF 约 90 秒）。
• 仅在用户明确表示"已有百度 OCR key 想复用"或"需要 MinerU 云 API"时，改走 Step 4A / 兼容分支，并说明这两条路径已非默认。

Step 2：检查 Python（Mac）

python3 --version

为什么要这步：新 Mac 预装的 Python 可能是 3.8 或更旧，跑 PyPDF2 会报奇怪的错。

• 版本 ≥ 3.9 → 直接下一步
• 版本 < 3.9 或报 command not found → 让用户跑 brew install [email protected]（如果没装 Homebrew 先跑下面这句）

Homebrew 未安装时先装：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Homebrew 是 macOS 的包管理器，后续所有系统级依赖都通过它安装。

Step 3：装所有依赖（一条命令）

brew install poppler
pip3 install -U -r "${CLAUDE_PLUGIN_ROOT}/requirements.txt"

requirements.txt 列了两组东西：

• 经典管道：opencv-python / pillow / pdf2image / PyPDF2 / python-docx 等——prep-scan / preview / to-docx / mp-format 用
• MinerU 本地管道：mineru[pipeline] + torch + torchvision + shapely + scikit-image——ocr-run 的默认路径用

整个 pip 过程约 5 分钟（包含 ~1 GB 的 torch）。如果 pip 报 externally-managed-environment（Homebrew Python 常见），加 --user：

pip3 install --user -U -r "${CLAUDE_PLUGIN_ROOT}/requirements.txt"

验证：

python3 -c "import cv2, PIL, requests, dotenv, markdown, PyPDF2, pdf2image, bs4, docx, yaml, opencc, mineru, torch, torchvision; print('依赖齐全')"
which mineru

第二行应该打印 mineru 的路径（说明 CLI 装上了）。输出「依赖齐全」才算过。

Step 3.5：预热 MinerU 模型（一次性）

第一次跑 mineru 会下载 ~2–3 GB 模型到 ~/.cache/huggingface/hub/。 在正式 OCR 一份 PDF 前让它先下好，省得第一次跑 PDF 时卡住。

让用户拿一份任意的小 PDF（一两页即可，扫描或文字层都行）当 probe； 仓库本身不附 sample PDF，避免把额外二进制塞进 git。

先把用户提供的 PDF 绝对路径赋给 USER_PROBE_PDF，再运行：

# 1) 把用户的 probe PDF 路径填进来（绝对路径，含空格请用引号）
USER_PROBE_PDF="/Users/<name>/Downloads/probe.pdf"

# 2) 用该 probe PDF 触发 MinerU 模型下载，跑完立刻退出
TMP=$(mktemp -d)
mineru -p "$USER_PROBE_PDF" -o "$TMP" -b pipeline -m auto -l ch