前言¶
在 DSH 里查手册、对照 PDF 页码时，常见做法是让模型描述路径、或依赖宿主自带的文件预览。前者容易猜错页（印刷页码与 PDF 页序不一致），后者不一定每个 profile 都能稳定打开本地 PDF。下面介绍社区插件 dsh-pdf-jump（维护者 taoziliyouchong）：装一次注册两个工具，默认在侧栏用本地渲染看图跳页，需要文字层时再走原生预览。
这是什么¶
dsh-pdf-jump 属于 DSH 插件目录中的「客户端」类插件。当前 package 版本为 0.1.2，许可证 MIT，源码在 GitHub。
它解决的是：在对话里用自然语言或固定命令打开本地 PDF，并按 PDF 页序（1 = 文件第一页）跳转或整本滚动浏览，结果以侧栏可点的文档行呈现。页码不从页脚推断印刷编号，避免手册里「全书页码」和「章-页」混用导致的错位。
核心功能¶
一个插件包装两个独立工具，另注册 /pdf 命令：
| 能力 | 说明 |
|---|---|
pdf-view（默认） |
本地把页面渲染成图：工具条输入页码跳转、方向键翻页；整本浏览时先铺缩略图，滚到哪页换高清，页顶也可输入页码。不依赖原生预览，任何 profile 都能用。 |
pdf-open |
走 DSH 原生 PDF 预览（客户端直接渲染，不生成图片、不起本地 HTTP、有文字层）。适合明确要「最快、能选中文字」时。 |
/pdf |
固定走 pdf-view 单页模式，不经过模型判断，例如 /pdf 繁易手册 300。 |
提取文字或读元数据不在本插件范围内；README 建议另装 dsh-pdf，使用 pdf_info / pdf_extract_text。
pdf-view 机制要点（来自官方 README）：
- 本地 HTTP 只绑
127.0.0.1，端口从 8731 起向上试，可复用同机其他 DSH 进程已起的服务；插件加载即启动，默认idleMinutes: 0表示整个 DSH 会话常驻。 - 使用
pdfjs-dist+@napi-rs/canvas渲成 PNG 缓存；调用时先暖当前页及前后各 2 页，打开后以当前页为中心向两侧各暖 6 页（可通过配置调整）。 - 整本浏览先用 0.8 倍 JPEG 缩略图，滚到可见页再换全尺寸 PNG；每页锚点如
#p40，整本页顶输入页码即滚到该页。 - 不上传 PDF 内容。
安装与启用¶
要求：DSH 带宿主 tools 与 systemPrompt 服务；Node 22.19+ 或 24+。兼容说明：DSH 0.2.1-rc.5 实测通过；0.3 起不保证（见 package.json 的 engines.dsh）。
已发布到 npm 时：
dsh plugin --profile web add dsh-pdf-jump
尚未发布时从 GitHub 安装：
dsh plugin --profile web add github:taoziliyouchong/dsh-pdf-jump
安装后重启 DSH。若使用其他 profile，将命令中的 web 换成你的 profile 名。
插件以当前 DSH 进程权限访问本地文件；安装前建议浏览仓库源码与 LICENSE，确认路径与许可符合你的环境。
典型用法¶
路径支持绝对路径、相对路径（相对会话工作目录）或文件名片段（如 NB系列 安装手册）。两个工具都会返回一条可点的文档行：pdf-open 指向文件本身；pdf-view 指向本地查看页。
| 你的意图 | 选用 |
|---|---|
| 打开 PDF、跳到第 N 页、整本翻 | pdf-view（page = PDF 页序） |
| 原生预览、不生成图片、可选中文字 | pdf-open 或说明「原生预览打开」 |
| 整本内跳到某页 | 整本页顶部页码框，或 URL 带 #p40 |
| 不让模型判断、直接开 | /pdf <文件或片段> [页码]（无页码时从第 1 页） |
可选配置写在 profile 的 patch 里，只影响 pdf-view：
- id: dsh-pdf-jump
name: dsh-pdf-jump
config:
port: 8731
scale: 2
idleMinutes: 0
prefetch: true
prefetchWindow: 6
roots:
- D:/manuals
roots 为文件名片段搜索的额外根目录；也可用环境变量 PDF_JUMP_ROOTS（Windows 用 ; 分隔，其他平台用 :）。
适用场景与注意¶
适合：在 DSH 侧栏对照安装手册、技术 PDF，按 PDF 页序快速跳页或整本浏览；Web 等 profile 下无法用原生预览时，用 pdf-view 仍可在侧栏看图。
限制与排查（摘自 README）：
pdf-view输出为图片，不能选文字、不能全文搜索；要文字用dsh-pdf。pdf-open依赖 DSH 自带原生 PDF 预览；没有该能力的环境请用默认pdf-view。- 侧栏空白或「已阻止」：侧栏浏览器可能拦截回环地址。将
127.0.0.1:8731（及 8732–8750 中实际端口）加入侧栏「允许访问的本机地址」，或将「网页链接默认打开方式」改为「默认浏览器」。 - 旧对话链接「拒绝连接」：端口被占导致换端口，或 PDF 已移动/删除；重新调用工具取新地址即可。
渲染依赖 @napi-rs/canvas 预编译二进制，覆盖 Windows / macOS / Linux 的 x64 与 arm64。
结尾¶
dsh-pdf-jump 把「本地 PDF + 按页序跳页 + 侧栏浏览」收成一套可复用的 DSH 工具：默认渲染看图、可选原生预览，并用 /pdf 绕过模型直接开档。插件信息可在社区目录 skillhub.cn/plugins/taoziliyouchong/dsh-pdf-jump 查看；安装命令、配置与故障说明以 GitHub 仓库 README 为准。DSH 插件生态由社区目录与仓库维护，与 DeepSeek / 幻方无官方从属关系。
