DeepSeek-TUI 近期热度不小。100 万 token 上下文窗口、全终端操作体验——这些特性让它成为很多开发者的主力编码助手。但一个明显的缺口是：V4 没有多模态能力，无法直接"看"PDF、图片或文档。你丢给它一份论文 PDF，它只能回一句"我无法处理文件"。

MCP 方案理论上能补上这个缺口——通过 MinerU MCP Server 把文档解析能力接入 DeepSeek-TUI。但实际踩过坑的都知道，当前 DeepSeek-TUI 的 MCP 连接存在已知的不稳定性问题，经常连不上或超时。这条路暂时走不通。

换个思路。DeepSeek-TUI 内置了一套 Skill 系统——一种 Agent 指令包机制，可以让终端 Agent 学会执行特定的外部工具。安装一个 PDF 解析 Skill 后，Agent 就能自动调用 mineru-open-api CLI 完成文档解析，再把结果返回给你。整个过程不经过 MCP，直接走 CLI 域通信，绕开了 MCP 不稳定的瓶颈。

Skill 是什么

Skill 不是后台服务，也不是插件。它是一组指令文件（SKILL.md），告诉 Agent “当用户需要解析 PDF 时，你应该运行这条命令，然后读取输出”。Agent 读取 Skill 后，会在本地终端执行对应的 CLI 工具，通过标准的 stdin/stdout/stderr 管道交换数据。

你需要两个组件：mineru-open-api CLI（负责实际解析 PDF）和 tanis90/pdf-converter-mineru Skill（告诉 Agent 如何调用这个 CLI）。

第一步：安装 CLI

mineru-open-api 是一个零依赖的单二进制 CLI 工具，不需要 Python 或 Node.js 运行时。安装命令因系统而异。

Windows（PowerShell）：

irm https://cdn-mineru.openxlab.org.cn/open-api-cli/install.ps1 | iex

Linux / macOS：

curl -fsSL https://cdn-mineru.openxlab.org.cn/open-api-cli/install.sh | sh

安装完成后，运行 mineru-open-api version 确认安装成功。

第二步：安装 Skill

两种方式可选。

方式一：用 DeepSeek-TUI 内置命令（推荐）

在 TUI 中直接输入：

/skill install github:tanis90/pdf-converter-mineru

DeepSeek-TUI 会自动从 GitHub 拉取仓库，放置到正确的 Skill 目录。

方式二：手动放置

克隆仓库到 DeepSeek-TUI 的全局 Skill 目录：

git clone https://github.com/tanis90/pdf-converter-mineru.git ~/.deepseek/skills/pdf-converter-mineru

确认目录结构是否正确：

~/.deepseek/skills/pdf-converter-mineru/SKILL.md

SKILL.md 是这个 Skill 的核心——它描述了能力范围、命令格式和参数规则。Agent 通过 load_skill 机制读取它，才知道遇到 PDF 时该做什么。

Skill 的工作流：两种模式

Skill 加载后，Agent 根据 SKILL.md 的指令，调用 mineru-open-api 的两种解析模式：

flash-extract 模式——免登录，零门槛。

• 无需 API Token，IP 限频防滥用
• 单文件最大 10 MB，不超过 20 页
• 输出 Markdown（公式和表格默认开启，OCR 默认关闭）
• 适合快速预览、小文件、Agent 自动摘要场景

extract 模式——高精度，需 Token。

• 需要设置 MINERU_TOKEN 环境变量
• 单文件最大 200 MB，不超过 200 页
• 支持 Markdown、HTML、LaTeX、DOCX、JSON 多格式输出
• 支持批量处理、--ocr 扫描件识别、--pages 指定页码范围
• 适合论文、合同、扫描版文档等对精度要求高的场景

Agent 的选择逻辑很直接：如果你只说"帮我看一下这个 PDF"，Agent 自动走 flash-extract；如果你明确要求提取表格、保留公式或处理长文档，Agent 会检查是否配置了 Token，有则切到 extract 模式。

实战演示

场景一：读论文，做总结

你在 TUI 中输入：

帮我总结一下这篇论文的核心方法：arxiv_paper.pdf

Agent 的调用链路：

1. 识别出你需要解析 PDF → 自动加载 pdf-converter-mineru Skill
2. 执行 mineru-open-api flash-extract arxiv_paper.pdf
3. CLI 将 PDF 转为 Markdown 输出到 stdout
4. Agent 读取 Markdown，根据内容生成摘要

返回结果类似：

这篇论文提出了一种基于 Transformer 的序列建模方法，主要贡献包括：①引入了多头自注意力机制，将序列建模复杂度从 O(n²) 降到 O(n)；②提出了位置编码方案，让模型同时捕捉 token 的语义和位置信息；③在 WMT 2014 英德翻译任务上达到 BLEU 28.4，超越此前所有结果。实验在三个数据集（WMT 英德、英法、以及 English Constituency Parsing）上进行，准确率相比当时最优 baseline 提升了 2.0 BLEU 以上。

场景三：批量处理技术文档

你有一整本 API 文档，想快速了解每个章节的主题：

把 ./docs/api-reference.pdf 按章节拆分，给我一个目录大纲

Agent 会执行 mineru-open-api extract ./docs/api-reference.pdf，读取返回的 Markdown 结构，根据标题层级自动梳理出章节大纲：

第 1 章：认证与授权（OAuth 2.0 + API Key）
第 2 章：核心接口（RESTful API，支持 CRUD）
第 3 章：错误码表（400/401/403/404/500 及处理建议）
第 4 章：限流策略（令牌桶算法，默认 1000 req/min）

场景二：提取扫描合同的关键条款

扫描件或者图片型 PDF 需要 OCR。你输入：

把这个合同扫描件提取成文字，标出金额条款：contract_scan.pdf

Agent 检查到你需要高精度 + OCR，且文件可能超过 flash 模式的限制，会切换策略：

1. 确认 MINERU_TOKEN 已配置
2. 执行 mineru-open-api extract contract_scan.pdf --ocr --pages 1-10
3. 将返回的 Markdown 呈现给你，并标注出包含金额的段落

如果未配置 Token，Agent 会提示你设置后再试。

进阶：参数控制与批量处理

你可以直接在自然语言中指定参数，Agent 会映射为 CLI 参数。

指定页码范围：

提取这个 PDF 的第 3-8 页：report.pdf

→ Agent 执行 mineru-open-api flash-extract report.pdf --pages 3-8

多格式导出：

把这个文档解析成 Markdown 和 Word：guide.docx

→ Agent 执行 mineru-open-api extract guide.docx -f md,docx -o ./output/

批量处理多个文件：

把当前目录下所有 PDF 解析成 Markdown

→ Agent 执行 mineru-open-api extract *.pdf -o ./results/

从文件列表批量处理：

papers.txt 里有 10 篇论文 URL，全部转成 Markdown

→ Agent 执行 mineru-open-api extract --list papers.txt -o ./papers_md/

extract 模式支持三种批量输入方式：位置参数（*.pdf）、--list（从文件读取输入列表）和 --stdin-list（从管道读取列表）。批量场景下 -o 必须是目录，否则 CLI 会报错。--concurrency 参数（当前版本预留）未来可用于控制并发数。

处理扫描件时显式开启 OCR：

这份合同是扫描件，帮我全文 OCR 后提取付款条款

→ Agent 执行 mineru-open-api extract contract_scan.pdf --ocr --language ch

--language 参数影响 OCR 识别效果，中日韩混排文档建议显式指定 ch，英文文档用 en。--ocr 会调用 PaddleOCR 引擎，对倾斜、模糊、低对比度的扫描件仍有较好的识别率。

Skill 方案 vs MCP 方案的取舍

对比维度	Skill + CLI	MCP Server
稳定性	高——纯 CLI 调用，不依赖 MCP 协议层	当前 DeepSeek-TUI 存在连接问题
后台进程	无——命令行执行，用完即退	需要持续运行 MCP Server 进程
安装复杂度	两步：装 CLI + 放 Skill	配置 JSON + 管理进程生命周期
文件大小上限	flash 10MB / extract 200MB	同（API 层面一致）
多格式输出	flash 仅 Markdown / extract 支持多格式	同
Token 需求	flash 免登录 / extract 需 Token	Flash 模式免 Key / 完整模式需 Token

Skill 方案的核心优势在于轻量和稳定——没有持久化进程，没有协议层的中间故障点。代价是依赖本地 CLI 安装，初次配置需要两步操作。而 MCP 方案一旦 DeepSeek-TUI 修复了连接问题，在配置管理上会更方便（统一在 MCP 配置文件中管理）。

如果你当前正被 DeepSeek-TUI 读不了 PDF 困扰，Skill + CLI 这条路线可以立刻解决问题。装好 CLI，放好 Skill，剩下的交给 Agent 自己判断用哪种模式。