前言¶
在 DeepSeek Harness（dsh）里处理任务时，内置的 read 只能返回普通文本文件内容；web_fetch 又会拒绝 application/pdf。遇到 PDF、表格或幻灯片，会话里往往退化成 curl 加临时 pip install pypdf 一类做法，既慢也不稳定。dsh-doc-reader 是社区维护者 reg4916 发布的 npm 插件，向智能体注册五个带类型的文档工具，支持按页、按表、按幻灯片抽取文本，并对扫描件做本地 OCR。
这是什么¶
dsh-doc-reader（GitHub：reg4916/dsh-doc-reader）的定位是：把 PDF、DOCX、XLSX、PPTX 以及常见纯文本格式，从本地路径或 http(s) URL 读成智能体可用的结构化文本。插件当前版本为 0.2.0，采用 MIT 许可证，依赖 dsh 引擎 >=0.2.0-rc.1 <0.3.0-0，并发布在 npm 包名 dsh-doc-reader 上。
核心功能¶
插件暴露五个工具，参数设计都支持 path 或 url，输出默认受 maxChars 限制（默认 60000，硬上限 400000）。
| 工具 | 作用 | 主要参数 |
|---|---|---|
doc_read |
通用读取：PDF、DOCX、XLSX、PPTX、TXT/MD/CSV/HTML；按魔数自动识别格式 | path | url，format，pages，sheet，maxRows，maxChars |
pdf_read |
按页输出 PDF，带 --- page N/M --- 标记与标题/作者元数据 |
path | url，pages（如 "1-3,7"），maxChars |
xlsx_read |
每个工作表一块，行内制表符分隔；按名称或从 1 开始的索引选表 | path | url，sheet，maxRows，maxChars |
doc_meta |
仅元数据：格式、大小、PDF 页数/标题、DOCX 属性、XLSX 表名、PPTX 幻灯片数 | path | url，format |
doc_ocr |
扫描 PDF 与图片（PNG/JPEG/WebP/BMP/TIFF/GIF）的 OCR，每页带置信度 | path | url，pages，langs，scale，maxChars |
README 建议对大文件先用 doc_meta 摸清结构，再按需读取指定页或表，避免一次拉满输出。
纯文本抽取与 OCR 分工明确：PDF 若只有图像层、没有可提取文字，会返回 (no extractable text on this page)，此时应改用 doc_ocr。DOCX 经 mammoth 转换，图表、批注与修订不会变成正文；XLSX 返回显示值而非公式，行数可用 maxRows 分页。
OCR 行为¶
doc_ocr 使用 tesseract.js 7（WebAssembly），全程本地运行，不上传文件。PDF 页通过 pdf-to-img（pdf.js + @napi-rs/canvas）栅格化，默认 scale 为 2（约 200 DPI）；CCITT G4、JBIG2 传真式扫描经 pdf.js 解码后再 OCR。默认语言为 rus+eng，可通过 langs 覆盖；README 说明语言顺序会影响西里尔与拉丁混排识别，首次使用会从网络下载语言包（约每种 4 MB）到 ~/.dsh/cache/dsh-doc-reader/tesseract，离线环境可设置 DSH_DOC_READER_OCR_LANG_PATH 与 DSH_DOC_READER_OCR_CACHE。单次 OCR 最多 20 页 PDF，可用 pages 收窄范围。
限制与安全¶
本地文件上限 50 MB；URL 下载超时 20 秒，同样 50 MB 上限。插件拒绝访问私有/本地主机（localhost、127.0.0.1、RFC1918、.local、.internal），仅允许 http(s)，避免被用作 SSRF；内网文件需先下载到本地再传 path。
安装与启用¶
可从 DSH 内置插件市场安装，或手动加入 profile。官方 README 给出的步骤如下。
进入 profile 目录并安装包：
cd ~/.dsh/profiles/desktop
npx pnpm add dsh-doc-reader
在 profile 的 package.json 里把 bundle 写进 dsh.profile.bundles：
"dsh": { "profile": { "bundles": ["dsh-doc-reader", "..."] } }
重启 DSH（插件在启动时加载；DSH 组合为全有或全无）。下一次会话中会出现上述五个工具。若用 pnpm 12 且提示忽略 tesseract.js 的 build script，README 说明那只是 OpenCollective 横幅，可用 pnpm approve-builds 或忽略，OCR 仍可工作。
本地开发时可安装工作副本：npx pnpm add link:~/dsh-plugins/dsh-doc-reader（路径按你的仓库位置调整）。
典型输出¶
doc_read 读 PDF 时，输出带文件名、来源、页范围与标题行，例如：
# invoice.pdf — PDF · 184.2 KB
# source: /work/invoice.pdf
# pages 1, 2 of 7 · title: Invoice 2026-10
--- page 1/7 ---
ACME Ltd — Invoice 0042
...
读 XLSX 时按表列出维度与单元格，例如：
# budget.xlsx — XLSX · 12.4 KB
# source: https://example.com/budget.xlsx
# sheets: Data, Second
## sheet "Data" — 3 rows × 3 cols
1 | Year | Revenue | Note
2 | 2024 | 1000 | ok
3 | 2025 | 2000 | Привет
OCR 结果会标注引擎、语言、页码与置信度，例如：
# scan.pdf — PDF (OCR) · 1.8 MB
# source: /work/scan.pdf
# OCR: tesseract rus+eng · pages 1, 2 of 12
--- page 1/12 (ocr, 91.4%) ---
INVOICE 2026-042
...
适用场景与注意¶
适合需要在 DSH 会话里稳定读合同 PDF、Excel 预算、PPTX 大纲，或处理扫描件/截图的智能体工作流；与临时在会话里装 Python PDF 库相比，工具边界清晰，且对大文件有元数据先行、分段读取的路径。
使用前请知悉：插件以当前 dsh 进程权限访问磁盘与网络，安装前应阅读 GitHub 仓库 源码与 MIT 许可证。社区插件目录 SkillHub 上的 dsh-doc-reader 页 与 DeepSeek / 幻方无官方从属关系，属于「一切皆插件」生态中的第三方条目。
路线图（README 列出的规划，尚未承诺时间表）包括 .doc、.rtf、.odt、.epub 读取器，OCR 布局 hints，向视觉模型提供页/表图像，以及会话内解析缓存。
结尾¶
dsh-doc-reader 补上了 DSH 在 PDF 与 Office 文档上的工具缺口：五个专用工具、本地 OCR、明确的体积与安全策略。若你的 profile 经常碰 PDF 或表格，可按 README 安装 bundle 并重启 DSH 后在新会话中直接使用。
- 目录页：https://www.skillhub.cn/plugins/reg4916/dsh-doc-reader
- GitHub：https://github.com/reg4916/dsh-doc-reader
