前言¶
在 DeepSeek Harness（DSH）里让模型读 PDF、Office 或 Markdown 时，常见做法是直接丢给某一种转换器。多栏论文在这套流程里很容易「看起来成功、实则读序错乱」：正文被拆成大量表格行，或左右栏逐行交错。DSH 社区插件 dsh-doc-router（维护者 Dantwz7，分类：工作流）把问题拆成两步：先用确定性探测判断文件真实格式与 PDF 版式，再推荐并调用对应的提取管线。
这是什么¶
dsh-doc-router 是注册在 DSH 上的文档路由插件。它提供 doc_route、pdf_markdown 两个工具，并在 runtime 技能层注册 doc-routing 技能，使「先路由再阅读」的规则在各工作区生效，而不必在每个仓库里单独放 skills/ 目录。
路由结论不调用模型、不联网、不消耗 token，属于确定性判定。
为什么要路由¶
README 用 Nature Letter 样例（nmat4749.pdf）和仓库内合成 PDF 对比过几种管线：布局感知的 pymupdf4llm 能按阅读顺序合并多栏；pypdf 文本可读但结构丢失；MarkItDown 会把正文碎成大量 | … | 表格行。在 two-column-reading-order.pdf、three-column.pdf 上，MarkItDown 会按页垂直扫过所有栏（左右/左中右交替），而 pdf_markdown 输出则是先左栏再右栏（或三栏依次）。插件的论点是：没有单一转换器通吃所有 PDF，需要先探测再选管线。
核心功能¶
| 能力 | 说明 |
|---|---|
doc_route |
识别格式、页数、是否有文本层、单栏/多栏估计，并给出推荐管线及逐页探测证据 |
pdf_markdown |
基于 PyMuPDF 的布局感知 PDF → Markdown；支持页码范围与写入磁盘 |
doc-routing skill |
引导模型在读取前先调用路由，避免误用 MarkItDown 处理多栏正文 |
仓库 fixtures 上 doc_route 的示例结论包括：two-column.pdf、three-column.pdf 等多栏带文本层 PDF 推荐 pdf_markdown；无文本层或扫描类场景会指向其他策略（如渲染为图像再核对）。简介中概括的其余类型由 MarkItDown 等管线处理，具体以每次 doc_route 返回的 recommend 为准。
安装与启用¶
环境要求¶
| 项 | 要求 |
|---|---|
| DSH | >=0.2.0-rc.1 <0.3.0-0 \|\| >=0.2.1-rc.1 <0.3.0-0 |
| Node | ^22.19.0 \|\| >=24.0.0 |
| Python | 3.9+（仅 PDF 版式探测与 pdf_markdown 需要） |
| PyMuPDF | 可选；未安装时插件仍可加载，doc_route 仍可按格式分类，版式探测与 pdf_markdown 会明确提示不可用 |
Python 解释器查找顺序（先命中先用）：config.pythonPath → 环境变量 DOC_ROUTER_PYTHON → DSH 自带 runtime → ~/.dsh/dsh-runtimes → PATH 上的 python。
安装插件¶
推荐通过 DSH 包管理器安装，并固定版本（避免最小发布龄策略解析到更旧构建）。安装后需重启 DSH。
plugin_manager action=install_bundle target="dsh-doc-router@0.6.1"
若使用 CLI，需把 <YOUR-PROFILE> 换成 DSH 实际启动所用的 profile；错误的 profile 名不会报错，而是新建空 profile 并把包装在那里，运行中的实例拿不到插件。
dsh plugin --profile <YOUR-PROFILE> add dsh-doc-router@0.6.1
不确定当前 profile 时，优先使用上面的 plugin_manager 命令。
启用 PDF 版式与转换¶
在插件解析到的 Python 上安装 PyMuPDF 相关包：
<the python the plugin resolved> -m pip install -U pymupdf pymupdf4llm
许可证为 MIT；PyMuPDF 为可选依赖，使用前请自行阅读插件仓库中的 license 说明。
典型用法¶
下面步骤与 README Quick start 一致，路径为仓库内可复现的 fixture（相对工作区路径）。
1. 先路由¶
调用 doc_route，查看格式、栏数估计与推荐管线：
doc_route({ path: "tests/fixtures/two-column.pdf" })
→ Routed tests/fixtures/two-column.pdf — format: pdf, pages: 1, text layer: yes, columns: multi-column (est 2)
Recommended pipeline: pdf_markdown
…
dsh-doc-router v0.6.1
默认提示语为英文；自 0.4.0 起可通过配置把说明改为中文（见下节）。
2. 再转换¶
多栏 PDF 按推荐调用 pdf_markdown：
pdf_markdown({ path: "tests/fixtures/two-column.pdf" })
→ Converted tests/fixtures/two-column.pdf (all 1 pages) — 3391 characters of Markdown. …
需要完整正文落盘时指定 output；内联输出超过 maxChars 时会截断并明确说明。
pdf_markdown({ path: "tests/fixtures/two-column.pdf", pages: "1", output: "paper.md" })
→ Converted tests/fixtures/two-column.pdf (pages 1) — wrote 3391 characters to paper.md.
两个工具均接受相对工作区的路径。
配置要点¶
除 pythonPath 外，README 配置节提到 noteLanguage: 'zh' 可将路由后的说明行改为中文；判定字段（如 recommend、probe）与语言无关。
适用场景与注意¶
适合需要在 DSH 工作流中稳定读取 PDF、Word、Excel 等文档、且希望模型不要「凭感觉选转换器」的开发者。多栏论文、期刊 PDF 应优先走 doc_route → pdf_markdown；公式、上下标或数字必须完全一致时，README 建议对相关页渲染为图像再核对。
安装前请注意：插件与 DSH 同一进程权限运行，安装前应阅读 GitHub 仓库 源码与 MIT 许可证；PyMuPDF 为可选组件，合规与部署环境需自行评估。社区目录 SkillHub 插件页 与 DeepSeek / 幻方无官方从属关系，仅为社区收录入口。
结尾¶
dsh-doc-router 的价值在于「Route before you read」：用确定性探测替代单一转换器，减少多栏 PDF 被静默打乱读序的风险。进一步了解实现与 fixtures 证据，见 GitHub：Dantwz7/dsh-doc-router 与 SkillHub 目录页。
