雨舒 / YUSHU　·　动手试　·　NO. 001

系列上篇：AI 文档解析与书籍 Skill 工作流

扫描版 PDF、复杂表格和图片里的文字，常常没法直接用于后续提问。这篇带你把文件先整理成 Markdown、结构化内容和提取图片；完成后，你能按返回路径核对产物，再让 AI 继续阅读和处理。

先复制这段提示词，让 AI 帮你部署

如果你使用 Windows 上的 Codex 或 WorkBuddy，可以直接把下面这段提示词发给 AI 编程助手。它会先检查环境，再根据项目说明安装；默认使用本机解析，不会擅自把文件上传到云端。完成后，先用你指定的一份非敏感文件核对输出。

请帮我在这台 Windows 电脑上部署 Yushu Document Parser，并严格以仓库的 README.md、SKILL.md 和安装脚本为准： https://github.com/lan99988/yushu-document-parser  请按以下步骤操作： 1. 检查 Git、Python 版本、可用磁盘空间和 NVIDIA GPU 状态。项目要求 Python 3.10–3.14。 2. 将仓库克隆到合适的工作目录，先阅读 README.md、SKILL.md 和 scripts/install.ps1，再执行安装。 3. 默认使用本机模式。除非我明确要求远程模式，否则不要把任何文档发送到服务器，也不要自行切换后端。 4. 如果没有可用 NVIDIA GPU，先告诉我 CPU 模式会慢一些，并等待我决定是否继续；不要替我选择。 5. 使用项目安装器把 document-parser MCP 和 Skill 安装到 Codex 与 WorkBuddy。保留并合并现有配置，确认安装器生成了备份；不要覆盖其他 MCP 条目。 6. 安装完成后，告诉我当前后端、输出目录、配置备份位置，以及需要重启哪些客户端。只有在我提供或指定了非敏感样例文件后，才用该样例做验证。  建议的 PowerShell 安装命令： git clone https://github.com/lan99988/yushu-document-parser.git Set-Location .\yushu-document-parser Set-ExecutionPolicy -Scope Process Bypass .\scripts\install.ps1 

如果你本来就有自己部署的 MinerU 私网 API，可以明确告诉 AI 使用远程模式。远程模式会把选中的文件上传到你配置的服务器解析；不要把 API 密钥发到公开聊天或提交到代码仓库。

为什么要先把文件整理成可用文本？

我们经常把报告、教材、扫描件和表格交给 AI，却发现它读不出扫描版 PDF、看不懂复杂版面，或只能处理复制出来的一小段文字。原因通常不是对话模型不会回答，而是文件还没有先被可靠地解析成它能使用的内容。

Yushu Document Parser 就是这个前置环节：它把 MinerU 文档解析引擎接入 Agent Skill 和 MCP。安装后，AI 客户端可以按 Skill 的指引调用解析工具，把支持的文件转成 Markdown 和结构化结果，再读取解析后的正文。

可以把它理解成“文档入口”：先把文件内容整理出来，再由 AI 根据你的问题继续阅读、归纳或处理。解析器本身不替你完成后面的摘要、翻译或知识库建设。

它是怎么工作的？

整个流程可以拆成三步：

第一步：Skill 告诉 AI 怎么用。 仓库里的 SKILL.md 说明什么时候解析文件、应该选择哪个工具、如何检查结果，以及长文如何分段读取。这样 AI 不必每次临时猜测操作方式。

第二步：MCP 把工具接到客户端。 安装器会为 Codex 和 WorkBuddy 注册 document-parser 服务。连接成功后，客户端可以调用同一组工具，不需要把解析逻辑塞进对话提示词里。

第三步：MinerU 解析并保存产物。 当前适配版本固定使用 OpenDataLab 官方 MinerU 4.0.7。解析结果保存在本机输出目录，AI 根据返回路径继续读取。

这套代码做的是适配和调度：连接客户端、运行解析、管理输入和输出。实际的 OCR、版面分析和文档内容提取由上游 MinerU 引擎完成。

能处理哪些文件？

项目目前开放的输入类型包括：

•　PDF；

•　PNG、JPG/JPEG、WEBP、BMP、TIF/TIFF 图片；

•　DOC/DOCX、PPT/PPTX、XLS/XLSX；

•　RTF、ODT/ODS/ODP、EPUB、OFD；

•　HTML/HTM、MHTML/MHT 网页归档；

•　CSV/TSV 表格数据。

纯文本文件（如 TXT、MD）本来就能直接阅读，通常不必经过解析器。

三个 MCP 工具，各做一件事

parse_document：解析单个文件

传入一个文件路径，返回解析状态、使用的后端、产物路径和一段短预览。PDF 和图片默认使用 standard 档；Office、EPUB、OFD、HTML 等原生文档默认使用 flash 档。

parse_documents：按顺序批量解析

传入一组明确的文件路径，服务会逐个处理并单独报告成功或失败。某个文件失败不会让后面的文件一起中断。它不会自行递归扫描整个文件夹。

read_parsed_text：读取解析后的正文

根据 Markdown 路径分段读取内容，默认一次读取最多 200 行，并提供继续读取的位置。这样长文不必一次性塞进对话上下文；只有明确需要全文时，才读取完整内容。

产物保存在本机，可以接着用

一次解析通常会生成 Markdown、结构化 JSON、中间结构 JSON，以及从文档中提取出来的图片。常见目录结构如下：

output/   文件名/     markdown.md     structured_content.json     middle_json.json     images/ 

默认输出位置是 %LOCALAPPDATA%\DocumentParser\output。重名文件或重复解析会使用新的目录，避免覆盖之前的结果。后续可以让 AI 读取 Markdown，也可以把图片交给有视觉能力的模型继续分析。

本机解析，还是自己的远程服务器？

默认是本机模式：文件由本机 MCP 读取，并在本机调用 MinerU 解析，不会发送给项目作者维护的服务器。Windows 安装器会创建隔离的 Python 环境、安装所需组件，并把 MCP 与 Skill 配置合并到客户端配置中；首次解析时可能需要下载模型。

如果电脑没有合适的 GPU，可以选择继续使用 CPU（速度可能较慢），也可以自行部署云端 API，再显式配置远程模式。远程模式会把所选文件上传到你指定的 MinerU 服务器，因此请确认服务器地址、访问控制和文件保留策略。仓库的云端模板以 Linux Docker Compose 为基础，建议通过 Tailscale 私网访问，不要把 API 直接暴露到公网。

无论选择哪种模式，工具入口和产物结构保持一致；某个后端失败时会明确报错，不会偷偷换到另一端处理。

它的边界也要讲清楚

•　图片会被提取保存，但解析器不会自动生成图片描述；需要理解图中含义时，交给视觉模型继续处理。

•　扫描质量、倾斜、手写内容、复杂表格和特殊字体都会影响识别效果，重要信息仍要人工复核。

•　工具处理的是明确提供的文件路径，不会默认遍历文件夹。

•　它负责解析和读取产物，不负责摘要、翻译、问答、分类、向量化或知识库写入。

和书籍技能搭配：先解析，再提炼

如果你的目标是把一本书整理成可复用的 AI 技能，可以把解析器作为前置步骤：先把 PDF 或 Office 文件转成 Markdown、提取配图，再把整理好的材料交给 Cognition-Loom-skills 项目中的 book-to-skill 继续做章节提炼、术语整理和速查内容生成。

两个项目可以分别安装和使用。yushu-document-parser 不会自动调用 book-to-skill；你可以在同一个 AI 客户端中安装两边的 Skill，再根据需要把解析结果交给后续流程。

代码来源与许可

本仓库的 MCP 适配器、Agent Skill、Windows 安装器和云端部署模板是独立整理的适配代码；真正执行文档识别的引擎来自 OpenDataLab 官方 MinerU 项目，当前适配版本为 MinerU 4.0.7。这个仓库不是 MinerU 的官方项目，也不包含 MinerU 源码、模型权重或运行环境；安装时会单独获取上游引擎。

本仓库代码采用 MIT License。MinerU 和模型各自有独立许可，使用前请阅读对应的上游条款；如果基于 MinerU 对外提供在线服务，也要留意上游关于服务标识的要求。

开始试用

项目地址：github.com/lan99988/yushu-document-parser

如果你正在处理书籍，也可以看看：Cognition-Loom-skills / book-to-skill。欢迎试用、提 Issue，也欢迎分享你最想让 AI 读懂的文档类型。