文档读取技能包

一个给 AI 智能体使用的本地文档读取技能包。它会把 PDF、扫描 PDF、DOCX、PPTX、XLSX、旧版 Office、图文混排报告、审计材料、漏洞报告等文件解析成智能体容易阅读和追溯的产物：document.md、document.json、页面图、嵌入图片、表格和 verification.md。

核心目标很简单：不要让智能体凭二进制文件乱猜内容，而是先在本地解析、保留证据，再基于可验证的中间产物回答。

特性

• 全程本地处理，不依赖云端 OCR、远程文档解析或在线转换服务。
• 预置 Windows / Linux CPython 3.13 的 vendor/wheelhouse，首次运行会自动创建本地 .venv 并安装依赖。
• PDF 默认使用 PyMuPDF，支持文本块、页面渲染和嵌入图片提取。
• DOCX、PPTX、XLSX 使用成熟本地 Office 解析库。
• pypdf 作为轻量 PDF 文本回退引擎。
• Docling、OCR 作为可选增强，不影响核心开箱即用体验。
• 输出 verification.md，提醒用户哪些页面、图片或低保真回退结果需要人工复核。

目录结构

document-reader-skill/
  README.md
  LICENSE
  THIRD_PARTY_NOTICES.md
  install.ps1
  install.sh
  document-reader/
    SKILL.md
    requirements-core.txt
    requirements-heavy-optional.txt
    scripts/
    references/
    vendor/wheelhouse/

其中 document-reader/ 是真正的技能包目录。安装时复制这个目录即可。

推荐安装方式：交给 AI 智能体

如果你的 AI 智能体可以读写本地文件、执行 git 和复制文件，可以直接把下面这段提示词发给它。你既可以提供仓库地址，也可以提供已经下载好的本地目录。

请帮我安装本地 document-reader 文档读取技能包。

仓库地址是：https://gitee.com/huohuopro/document-reader.git

如果我已经提供了本地目录，请直接使用那个目录；如果没有本地目录，请你自行选择一个临时或工作目录执行 git clone。

请你执行以下步骤：
1. 先确认本机是否有 git；如果没有 git，就提示我手动下载仓库压缩包并解压。
2. 获取仓库后，检查仓库目录下是否存在 document-reader/SKILL.md、document-reader/scripts/read_document.py、document-reader/vendor/wheelhouse。
3. 将仓库里的 document-reader 文件夹复制到我的智能体技能目录：
   - 如果我是 Hexiaoan / Hermes 用户，优先复制到 %USERPROFILE%\.hermes\skills\productivity\document-reader
   - 如果我是 Codex 用户，复制到 %USERPROFILE%\.codex\skills\document-reader
   - 如果你能从当前环境判断实际技能目录，请使用实际目录
4. 不要复制运行产物：.venv、.document-reader、__pycache__、*.pyc。
5. 安装后告诉我需要重启智能体才能加载新技能包。
6. 重启后，请用一个本地 PDF 或 DOCX 测试：
   <skill-dir>\scripts\run_with_bundled_python.ps1 "C:\path\to\test.docx"
   确认它会从 vendor/wheelhouse 创建 .venv，并输出 .document-reader/runs 下的 document.md、manifest.json、verification.md。

Linux/macOS 用户可把上面的目标目录和测试命令替换为：

目标目录优先使用：~/.hermes/skills/productivity/document-reader 或 ~/.codex/skills/document-reader
测试命令使用：<skill-dir>/scripts/run_with_bundled_python.sh /path/to/test.pdf

手动安装

Hexiaoan / Hermes

Windows：

.\install.ps1

或者手动复制：

Copy-Item -Recurse .\document-reader "$env:USERPROFILE\.hermes\skills\productivity\document-reader"

Linux：

./install.sh

或者手动复制：

mkdir -p ~/.hermes/skills/productivity
cp -r ./document-reader ~/.hermes/skills/productivity/document-reader

Codex

Windows：

Copy-Item -Recurse .\document-reader "$env:USERPROFILE\.codex\skills\document-reader"

Linux：

mkdir -p ~/.codex/skills
cp -r ./document-reader ~/.codex/skills/document-reader

复制后请重启智能体。

使用方法

在任意工作区运行：

& ".\document-reader\scripts\run_with_bundled_python.ps1" "C:\path\to\document.pdf"

如果已经安装到 Hermes 技能目录：

& "$env:USERPROFILE\.hermes\skills\productivity\document-reader\scripts\run_with_bundled_python.ps1" "C:\path\to\document.pdf"

Linux：

./document-reader/scripts/run_with_bundled_python.sh /path/to/document.pdf

也可以直接运行 Python 入口：

python .\document-reader\scripts\read_document.py "C:\path\to\document.pdf"

首次运行时，read_document.py 会自动从 document-reader/vendor/wheelhouse/<platform> 创建并安装 document-reader/.venv，然后重新进入该虚拟环境运行。

输出结果

默认输出到当前工作区：

.document-reader/
  latest.json
  runs/
    <timestamp>_<source-name>/
      document.md
      document.json
      manifest.json
      verification.md
      pages/
      images/
      tables/
      logs/

建议阅读顺序：

1. verification.md：先看 warnings 和质量检查。
2. document.md：主 Markdown 内容。
3. manifest.json：解析引擎、源文件、artifact 路径。
4. pages/、images/、tables/：当 verification 提醒需要复核页面图、图片或表格时查看。

重建离线依赖包

仓库默认带 Windows / Linux 的 CPython 3.13 wheel 离线依赖包。若你的用户使用其他 Python 版本或平台，需要重建。

Windows：

.\document-reader\scripts\build_wheelhouse.ps1 -Python python

Linux：

./document-reader/scripts/build_wheelhouse.sh

包含可选重型引擎：

.\document-reader\scripts\build_wheelhouse.ps1 -IncludeHeavy

INCLUDE_HEAVY=1 ./document-reader/scripts/build_wheelhouse.sh

注意事项

• .venv/、.document-reader/、__pycache__/ 和测试输出不应提交。
• vendor/wheelhouse/ 是故意保留的，这样用户可以享受官方技能包那种开箱即用体验。
• 旧版 .doc、.ppt、.xls 需要本地 LibreOffice 或 Windows Office COM 转换支持。
• OCR 引擎是可选增强，可能需要额外安装本地运行时。