mineru-prime

PDF → 干净 Markdown：MinerU 解析 + mineru-refine 清洗

全链路两段：① MinerU 官方 API 把文件解析成 content_list.json + images → ② mineru-refine 后处理清洗，产出 drop-in 替身目录（清洗版 content_list + 重渲染 full.md + 审计报告）。

两段都靠仓库脚本驱动，运行时统一 bun。本 plugin 默认把三层 opt-in 清洗 （OCR 形近字修正 / 乱码表视觉重转写 / 乱码表降级兜底）全开——最大限度清洗， 输出契约从"只删不增"转为双契约（有逾点全部留痕、可审计、可程序化撤销）。

前置：两个命令 + 工作目录

• 命令：plugin 的 bin/ 已自动进 PATH，直接当命令调，不用关心脚本在哪、不依赖 $CLAUDE_PLUGIN_ROOT：

  • mineru-prime-fetch <输入文件> <产物目录> —— MinerU 解析
  • mineru-prime-refine <产物目录> [清洗输出目录] —— refine 清洗（首次运行自动装依赖）

  若极少数环境里这两个命令不在 PATH（command -v mineru-prime-refine 为空）， 回退用 $CLAUDE_PLUGIN_ROOT/bin/mineru-prime-refine，再不行用 find ~/.claude/plugins -name mineru-prime-refine 2>/dev/null 定位。

• 工作目录 $WORKDIR：放 .env 和产物的地方。默认用户当前目录下的 mineru-refine-out/ （不存在就建）；用户指定了输出位置就用用户的。两个命令都从 $WORKDIR 运行 （cd "$WORKDIR" && mineru-prime-...），因为 bun 从 cwd 自动加载 .env 里的 key。

步骤

1. 确认输入文件

• 用户给一个待处理文件路径。支持 pdf / doc / docx / ppt / pptx / png / jpg / jpeg / html。
• 路径不存在或类型不支持 → 停下来问用户，不要瞎跑。

2. 环境检查 + 三个 key（写 .env 持久化）

• bun：command -v bun。没有就停下来引导安装（curl -fsSL https://bun.sh/install | bash）， 装好再继续——别用别的运行时凑合。

• key：检查 $WORKDIR/.env 是否已含以下三个。缺哪个就向用户要哪个， 然后写进 $WORKDIR/.env（持久化，下次免输）。已存在的不要覆盖、不要打印 key 值。

  key	必需性	用途
  MINERU_API_TOKEN	解析必需	MinerU 官方 API 解析（https://mineru.net 申请）
  DEEPSEEK_APIKEY	清洗必需	refine 文本裁决主力；缺则 refine 直接 fail-open
  QWEN_APIKEY	清洗强烈建议	跨页拆表视觉裁决 + 乱码表视觉重转写；缺则这两类整体搁置

  三个都给齐再往下；用户坚持不给 QWEN_APIKEY 就照常跑，但提醒他视觉相关清洗会被搁置。

3. 解析（MinerU）

cd "$WORKDIR" && mineru-prime-fetch "<输入文件绝对路径>" "$WORKDIR/mineru"

• 这一步会上传文件、轮询 MinerU（大文件可能几分钟，脚本内置 20 分钟超时），下载 zip 解包， 归一化出 $WORKDIR/mineru/content_list.json + images/。
• 脚本末行是一行 JSON（{ok, stem, outDir, items}）——读它确认产物与 item 数。
• 失败（HTTP 错 / 解析 failed / 超时）会抛异常，原样把错误告诉用户，别吞。

4. 清洗（mineru-refine，三层全开）

cd "$WORKDIR" && mineru-prime-refine "$WORKDIR/mineru" "$WORKDIR/refined"

首次运行会自动 bun install 把 mineru-refine 原生绑定装进 plugin 的 scripts/node_modules（幂等，之后秒过）。

• 产出 drop-in 替身目录 $WORKDIR/refined/：images/、layout.json 原样镜像 （img_path 不断链），content_list.json 是清洗版，full.md 确定性重渲染， 另有 refine_report.json 审计报告。
• 脚本末行是一行 JSON 摘要——读它拿前后疑点数、ops、留痕数、token、failOpen 等。
• failOpen=true 意味着触发了兜底（异常/key 缺失/LLM 不可用），refined 内容即原始输入—— 要明确告诉用户没真正清洗到，并查 refine_report.json 找原因（多半是 DEEPSEEK_APIKEY 问题）。

5. 汇报

给用户一段简明小结，基于第 4 步的摘要 JSON：

• 疑点 前 → 后（suspectsBefore → suspectsAfter）：清洗整体效果。
• 各修复操作次数（opCounts）+ 降级/删除留痕条数（removedSpans）。
• 三层 opt-in 落地量：confusionFixes（OCR 形近字替换）/ tableRewrites（乱码表整格重转写） / tableDegraded（救不回降级为图片的表数）。
• token 花费（tokenUsage）与 是否 failOpen。
• 产物位置：$WORKDIR/refined/——指明 full.md 是干净 markdown 成品， content_list.json 可直接 drop-in 替换原 MinerU 结果喂下游，refine_report.json 可逐条审计。

不要轮询、不要后台挂着；跑完即汇报。

硬约束（照搬 mineru-refine 的承诺，别违背）

• fail-open 优先：任何异常都应让脚本大声抛、原样把错误转达用户，绝不静默吞或伪造成功。
• 不替用户编内容：full.md / content_list 全部来自 refine 的产物，不要手工增删其中文字。
• key 不外泄：不在对话或日志里回显任何 key 值；写 .env 即可。