dsh-pdf-jump 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-pdf-jump contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,103 @@
+# dsh-pdf-jump
+
+[中文](README.md) | **English**
+
+Read local PDFs **inside the DSH sidebar**. One install ships two independent tools:
+
+- **`pdf-view` (default)** — renders pages locally for **jumping to a page number** and **whole-document browsing**. The whole-document view fills the list with thumbnails first, swaps each page to full size when it scrolls into view, and has a page box at the top. Works anywhere, even without the native preview.
+- **`pdf-open`** — opens the PDF with **DSH's native PDF preview** (client-side rendering, no image generation, no local server, selectable text). Used when you explicitly ask for the native preview, the fastest path, or no images.
+
+Page numbers follow **PDF page order** (1 = first page of the file). The plugin deliberately does not infer the number printed in a footer: manuals often mix whole-book numbering with `chapter-page` numbering.
+
+![Page viewer](assets/screenshot-page.png)
+
+Jump by page number: type it in the toolbar; arrow keys flip pages.
+
+![Whole-document view](assets/screenshot-document.png)
+
+Whole-document view: thumbnails first, full size as each page scrolls into view, with a page box at the top.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-pdf-jump
+```
+
+Before the package is on npm, install straight from GitHub:
+
+```sh
+dsh plugin --profile web add github:taoziliyouchong/dsh-pdf-jump
+```
+
+Then restart DSH. Replace `web` with your profile name if you use another one.
+
+After the restart a `/pdf` command is registered as well: `/pdf manual 300` returns the link without going through the model.
+
+Requirements: DSH with the host `tools` and `systemPrompt` services (both are part of the normal base composition), Node 22.19+ or 24+.
+
+Compatible with the DSH 0.2.1 line (alpha / rc / stable); 0.3 and later are not guaranteed.
+
+## Use
+
+| You want | Tool |
+| --- | --- |
+| Open a PDF, jump to page N, browse the whole document | `pdf-view` (default; `page` = PDF page number) |
+| Native preview (no images, selectable text) | `pdf-open` |
+| Jump to a page inside the whole-document view | Page box at the top, or a `#p40` URL |
+| Skip model judgement and open directly | `/pdf <file or fragment> [page]` |
+| Extract text / metadata | install the `dsh-pdf` plugin and use its `pdf_info` / `pdf_extract_text` |
+
+Both tools accept an absolute/relative path or a file-name fragment (for example `NB系列 安装手册`); relative paths resolve against the session working directory. Results are one clickable document line: `pdf-open` points at the file itself (opened by the native preview), `pdf-view` points at the local viewer page.
+
+## How it works
+
+- `pdf-open` only resolves the path and returns it for `sidebar_open`; all rendering happens in the DSH client.
+- `pdf-view` runs a local HTTP server bound to `127.0.0.1`; it tries ports 8731–8750, reuses a server already started by another DSH process, and starts as soon as the plugin loads. It stays up for the whole DSH session (`idleMinutes: 0`), so links from earlier conversations keep working.
+- `pdf-view` renders pages with `pdfjs-dist` and `@napi-rs/canvas` into PNGs cached in the OS temp directory. A call warms the requested page ±2; opening a page warms ±`prefetchWindow` around it, outward one step at a time. Cached pages are served directly without entering the render queue.
+- Whole-document view fills the list with 0.8× JPEG thumbnails first (a dozen milliseconds per page) and swaps each page to the full-size PNG as it scrolls into view. Every page carries an anchor (`#p40`); the page box at the top scrolls to the requested page.
+- The `/pdf` command always goes through `pdf-view` (single-page mode), starting at page 1 when no page is given; call `pdf-open` directly (or ask for the native preview) when you want the native viewer.
+- Viewer URLs are short paths (`/v/<id>/<page>`, `/d/<id>`, `/p/<id>/<page>.png`, `/t/<id>/<page>.jpg`) with no query string; the id maps to the file through a small registry in the temp directory. Combined with the eager start on the same port, a link from an earlier conversation opens again after DSH restarts.
+- Nothing is uploaded.
+
+## Configuration
+
+Optional, in the profile patch row (affects `pdf-view` only):
+
+```yaml
+- id: dsh-pdf-jump
+  name: dsh-pdf-jump
+  config:
+    port: 8731
+    scale: 2
+    idleMinutes: 0
+    prefetch: true
+    prefetchWindow: 6
+    roots:
+      - D:/manuals
+```
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `port` | `8731` | First port to try; the server scans upward for a free or already-running instance |
+| `scale` | `2` | Render scale; 2 is roughly 144 dpi |
+| `idleMinutes` | `0` | Shut the server down after this many idle minutes; `0` keeps it running for the DSH session |
+| `prefetch` | `true` | Warm pages around the current one in the background |
+| `prefetchWindow` | `6` | How many pages on each side of the current page to warm |
+| `roots` | `[]` | Extra search roots for file-name fragments |
+
+`PDF_JUMP_ROOTS` (environment variable) adds search roots as well, separated by the platform path delimiter (`;` on Windows, `:` elsewhere).
+
+## Limitations
+
+- `pdf-open` relies on DSH's built-in PDF preview; use the default `pdf-view` where that preview is absent.
+- `pdf-view` pages are images: no text selection and no full-text search. Install the `dsh-pdf` plugin and use its `pdf_extract_text` when you need the text.
+- Rendering needs the `@napi-rs/canvas` prebuilt binary, which covers Windows, macOS and Linux on x64/arm64.
+
+## Troubleshooting
+
+- **The sidebar shows a blank page or "blocked"** (for `pdf-view` URLs): the in-app Sidebar Browser blocks loopback addresses unless they are allowlisted. Add `127.0.0.1:8731` (and whichever port in 8732–8750 is in use), or set *Settings → General → Open chat links in* to the default browser.
+- **A link from an older conversation says "connection refused"**: either the viewer port changed (another program holds 8731) or the PDF file moved. Call the tool again for a fresh link; `pdf-open` paths are unaffected.
+
+## License
+
+MIT

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# dsh-pdf-jump
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**中文** | [English](README.en.md)
+
+在 DSH 侧栏里看本地 PDF。一个包装两个独立工具，装一次两个都可用：
+
+- **`pdf-view`（默认入口）**：本地把页面渲染成图——**按页码跳**、**整本浏览**；整本页先出缩略图、滚到哪页换高清，页顶还能输入页码直接跳。不依赖原生预览，任何 profile 都能用。
+- **`pdf-open`**：用 DSH **原生的 PDF 预览**打开（客户端直接渲染，不生成图片、不起本地服务、有文字层）；只在明确要「原生预览、不生成图片、最快」时用。
+
+页码按 **PDF 页序**（1 = 文件第一页）。不从页脚推断印刷页码：手册常把全书页码和「章-页」编号混着用，猜出来的差值会把正文页整体错位。
+
+![单页查看器](assets/screenshot-page.png)
+
+按页码跳页：工具条里输入页码直接跳到那一页，方向键翻页。
+
+![整本浏览](assets/screenshot-document.png)
+
+整本浏览：缩略图先铺满，滚到哪页换高清；顶部也有页码框，输入即跳。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-pdf-jump
+```
+
+还没发布到 npm 时，直接从 GitHub 装：
+
+```sh
+dsh plugin --profile web add github:taoziliyouchong/dsh-pdf-jump
+```
+
+然后重启 DSH。用别的 profile 就把 `web` 换成你的 profile 名。
+
+装好后除了两个工具，还会注册一个 `/pdf` 命令：`/pdf 繁易手册 300` 直接出链接，不经过模型判断。
+
+要求：DSH 带宿主 `tools` 与 `systemPrompt` 服务（普通基础组合都含），Node 22.19+ 或 24+。
+
+兼容：DSH 0.2.1 系列（alpha / rc / 正式版均可）；0.3 起不保证。
+
+## 用法
+
+| 你说 | 用哪个工具 |
+| --- | --- |
+| 打开某本 PDF、跳到第 N 页、整本翻 | `pdf-view`（默认；page = PDF 页序） |
+| 要原生预览（不生成图片、能选中文字） | `pdf-open` |
+| 在整本里跳到某页 | 整本页顶部输入页码，或地址带 `#p40` |
+| 不让模型判断、直接开 | `/pdf <文件或片段> [页码]` |
+| 提取文字 / 读元数据 | 另装 `dsh-pdf` 插件，用它的 `pdf_info` / `pdf_extract_text` |
+
+两个工具都接受绝对/相对路径或文件名片段（如 `NB系列 安装手册`）；相对路径按会话工作目录解析。结果都会显示成一条可点的文档行，`pdf-open` 指向文件本身（由侧栏原生预览打开），`pdf-view` 指向本地查看页。
+
+## 机制
+
+- `pdf-open` 只解析路径并返回文件路径，交给 `sidebar_open`；渲染完全由 DSH 客户端完成。
+- `pdf-view` 的本地 HTTP 服务只绑 `127.0.0.1`，端口从 8731 往上试，复用别的 DSH 进程已起的服务；插件一加载就启动，整个 DSH 会话期间常驻（`idleMinutes: 0`），旧对话里的链接不用重新生成。
+- `pdf-view` 用 `pdfjs-dist` + `@napi-rs/canvas` 把页面渲成 PNG 缓存在系统临时目录；工具一调用先暖请求页和前后各 2 页，打开后以当前页为中心向两边各暖 6 页，已缓存的页直接读盘、不进渲染队列。
+- 整本浏览先用 0.8 倍 JPEG 缩略图铺满（每页十几毫秒），滚到哪页再把那页换成全尺寸 PNG；每一页都有锚点（`#p40`），整本页顶部输入页码即滚到该页。
+- `/pdf` 命令固定走 `pdf-view`（单页跳转模式），不带页码时从第 1 页起；要原生预览就直接调 `pdf-open`，或说「原生预览打开」。
+- 查看地址是短路径（`/v/<id>/<页>`、`/d/<id>`、`/p/<id>/<页>.png`、`/t/<id>/<页>.jpg`），不带查询串；id 通过系统临时目录里的小注册表映射到文件。配合「插件加载即启动、端口固定」，DSH 重启后旧对话里的链接也能重新打开。
+- 不上传任何内容。
+
+## 配置
+
+可选，写在 profile 的 patch 行里（只影响 `pdf-view`）：
+
+```yaml
+- id: dsh-pdf-jump
+  name: dsh-pdf-jump
+  config:
+    port: 8731
+    scale: 2
+    idleMinutes: 0
+    prefetch: true
+    prefetchWindow: 6
+    roots:
+      - D:/manuals
+```
+
+| 字段 | 默认 | 含义 |
+| --- | --- | --- |
+| `port` | `8731` | 起始端口；被占用或已有同款服务时自动向上找 |
+| `scale` | `2` | 渲染倍率，2 约等于 144 dpi |
+| `idleMinutes` | `0` | 空闲多少分钟后关掉服务；`0` 表示整个 DSH 会话常驻 |
+| `prefetch` | `true` | 是否在后台暖当前页附近的页面 |
+| `prefetchWindow` | `6` | 当前页两侧各暖多少页 |
+| `roots` | `[]` | 文件名片段搜索的额外根目录 |
+
+环境变量 `PDF_JUMP_ROOTS` 也可以加搜索根，按平台的路径分隔符分隔（Windows 是 `;`，其他是 `:`）。
+
+## 限制
+
+- `pdf-open` 依赖 DSH 自带的原生 PDF 预览；没有该预览的环境用默认的 `pdf-view`。
+- `pdf-view` 的页面是图片：不能选文字，也不能全文搜索；要文字另装 `dsh-pdf` 插件，用它的 `pdf_extract_text`。
+- 渲染依赖 `@napi-rs/canvas` 的预编译二进制，覆盖 Windows / macOS / Linux 的 x64 与 arm64。
+
+## 打不开时
+
+- **侧栏空白或提示「已阻止」**：应用内侧栏浏览器默认拦截本机回环地址。把 `127.0.0.1:8731`（及 8732–8750 中实际用到的）加进侧栏设置的「允许访问的本机地址」，或把「设置 → 通用 → 网页链接默认打开方式」改成「默认浏览器」。
+- **旧对话里的链接提示「拒绝连接」**：要么端口被别的程序占了导致换了端口，要么 PDF 文件被移动/删除。重新调用一次工具取新地址；`pdf-open` 返回的文件路径不受影响。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-pdf-jump：一个包装两个独立插件行。
+#   dsh-pdf-jump         — pdf-view：本地渲染页面（跳页 / 整本浏览 / 缩略图）
+#   dsh-pdf-jump/native  — pdf-open：用 DSH 原生 PDF 预览打开（最快）
+- insert:
+    - id: dsh-pdf-jump
+      name: dsh-pdf-jump
+    - id: dsh-pdf-jump-native
+      name: dsh-pdf-jump/native

package/index.js

@@ -0,0 +1,171 @@
+/**
+ * 类型：工具；解决：侧栏 iframe 不渲染 PDF，手册要按页翻、按页跳；
+ * 作用：本地把页面渲成图，给出带翻页 / 跳页 / 整本浏览的网页地址（页码按 PDF 页序）。
+ *
+ * 不 import 任何 DSH 包：工具定义按 ctx.tools.register 的形状直接写，换 DSH 版本不受影响。
+ */
+
+import { basename, resolve } from 'node:path'
+
+import { resolvePdf } from './lib/resolve.mjs'
+import { createViewer, registerFile } from './lib/server.mjs'
+
+/** Cordis 插件名。 */
+export const name = 'dsh-pdf-jump'
+/** 需要的服务：工具注册表 + 系统提示（让模型知道什么时候该用它）+ 命令注册表（/pdf）。 */
+export const inject = ['tools', 'systemPrompt', 'commands']
+
+/**
+ * 每轮都在模型上下文里的使用说明。工具描述只在工具列表里出现一次，
+ * 这段公告把「什么时候用 / 什么时候不用」说清楚，保证模型选得对。
+ */
+const GUIDANCE = [
+  '本机装了 dsh-pdf-jump（在侧栏里看 PDF，两个独立入口）：',
+  '- 默认用 pdf-view（单页跳转模式）：带页码打开，页面带「上一页/下一页/跳页码/整本浏览」。用户只说「打开/看一眼某本 PDF」「打开第 N 页」也一律用它。',
+  '- pdf-open 只在明确要求「原生预览、不生成图片、最快」时才用，不作为默认。',
+  '- 用户要提取 PDF 文字、读元数据或比较字体时，用 dsh-pdf 插件（需另装）的 pdf_info / pdf_extract_text，不要用这两个工具。',
+  '- 不要绕过这两个工具自己用 sidebar_open 打开 PDF 文件：那样没有跳页、没有整本浏览；pdf-open 返回的路径再交给 sidebar_open 才是正确顺序。',
+  '- 两个工具都返回本机路径或本地 url：有 sidebar_open 就先调它开在侧栏；不要把裸路径/裸 url 贴给用户，用「📄 文件名」做链接文字。',
+  '- 只给了文件名片段、不知道路径时直接传进去：先按会话工作目录找，再按片段搜。',
+  '- 用户说「点了链接没反应 / 打不开」时，说明是侧栏浏览器默认拦截本机地址：建议把「网页链接默认打开方式」改成默认浏览器，或把 127.0.0.1:<端口> 加进侧栏设置里的本机地址白名单。',
+  '- 旧对话里的 url 在服务空闲退出后会失效，不要复用；每次重新调用取新地址。',
+].join('\n')
+
+const parameters = {
+  type: 'object',
+  properties: {
+    file: { type: 'string', description: 'PDF 绝对/相对路径，或文件名片段（如 "VFD-EL-W 手册"）' },
+    page: { type: 'number', description: 'PDF 页序（从 1 开始），不是页脚印的印刷页码' },
+    cwd: { type: 'string', description: '搜索根目录；默认用当前会话的工作目录' },
+  },
+  required: ['file', 'page'],
+}
+
+const output = {
+  schema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      ok: { type: 'boolean' },
+      url: { type: 'string' },
+      file: { type: 'string' },
+      page: { type: 'number' },
+    },
+    required: ['ok', 'url', 'file', 'page'],
+  },
+  render: (_args, value) => [{
+    type: 'text',
+    text: `[📄 ${basename(value.file)} · 第 ${value.page} 页](<${value.url}>)`,
+  }],
+}
+
+/** 当前会话的工作目录；取不到时退回进程目录。 */
+function sessionCwd(ctx, exec) {
+  try {
+    const workingDirectory = ctx.get?.('workingDirectory')
+    const session = exec?.agent?.session
+    if (workingDirectory && session) return workingDirectory.get(session)
+  } catch { /* 老版本没有这个服务，用进程目录 */ }
+  return process.cwd()
+}
+
+export function apply(ctx, config = {}) {
+  const viewer = createViewer({
+    port: config.port,
+    scale: config.scale,
+    idleMinutes: config.idleMinutes,
+    prefetch: config.prefetch,
+    prefetchWindow: config.prefetchWindow,
+  })
+  const extraRoots = Array.isArray(config.roots) ? config.roots.map(String) : []
+
+  let starting = null
+  const ensureViewer = () => {
+    // start() 自己会复用已在跑的服务；服务因空闲退出后再次调用会重新拉起。
+    if (!starting) starting = viewer.start().finally(() => { starting = null })
+    return starting
+  }
+
+  ctx.effect?.(() => () => { viewer.stop().catch(() => {}) })
+
+  // 插件加载就把服务起起来。DSH 重启后还是同一个默认端口、同一份路径注册表，
+  // 旧对话里的 /v、/d 链接可以直接重新打开；端口被占用时工具调用会再试。
+  viewer.start().catch(() => {})
+
+  const hasTool = (name) => {
+    try {
+      return typeof ctx.tools.get === 'function' && ctx.tools.get(name) !== undefined
+    } catch {
+      return false
+    }
+  }
+
+  if (!hasTool('pdf-view')) {
+    try {
+      ctx.tools.register({
+        name: 'pdf-view',
+        description:
+          '在侧栏里看本地 PDF（默认入口）：单页跳转模式，页面带「上一页/下一页/跳页码/整本浏览」；'
+          + '打开某本 PDF、翻到第 N 页、整本浏览都用它。pdf-open 只在明确要原生预览时用；要提取文字或元数据用 dsh-pdf 插件（需另装）的 pdf_info / pdf_extract_text。'
+          + '本地服务把该页渲染成图，返回带「上一页/下一页/跳页码/整本浏览」的侧栏网页地址。'
+          + 'file 给 PDF 路径或文件名片段（相对路径按会话工作目录解析），page 给 PDF 页序（从 1 开始，不从页脚推断印刷页码）。'
+          + '返回 url：有 sidebar_open 就交给它打开；不要把裸 url 贴给用户。首次调用自动拉起本地服务（只绑 127.0.0.1）。',
+        parameters,
+        output,
+        isConcurrencySafe: () => true,
+        async execute(args, exec) {
+          const cwd = args.cwd ? resolve(String(args.cwd)) : sessionCwd(ctx, exec)
+          const pdf = resolvePdf(args.file, cwd, extraRoots)
+          const port = await ensureViewer()
+          const page = Math.max(1, Math.round(Number(args.page) || 1))
+          const id = registerFile(pdf)
+          // 工具一返回就在后台把这一页和附近几页渲进缓存，用户点开时直接取图。
+          if (config.prefetch !== false) viewer.prefetch(pdf, page)
+          const url = `http://127.0.0.1:${port}/v/${id}/${page}`
+          return { ok: true, url, file: pdf, page }
+        },
+      })
+    } catch (err) {
+      console.warn(`[dsh-pdf-jump] 未注册 pdf-view：${err.message}`)
+    }
+  }
+
+  // 常驻说明：描述两个工具的分工；没有 systemPrompt 服务时静默跳过。
+  const systemPrompt = ctx.get?.('systemPrompt')
+  if (systemPrompt && typeof systemPrompt.section === 'function') {
+    ctx.effect?.(
+      () => systemPrompt.section({ name: 'plugin:dsh-pdf-jump', order: 161, text: GUIDANCE }),
+      'dsh-pdf-jump: guidance',
+    )
+  }
+
+  // 命令层：完全不经过模型判断，用户输入 /pdf 就一定走这两个工具。
+  try {
+    const commands = ctx.commands ?? ctx.get?.('commands')
+    if (commands && typeof commands.register === 'function') {
+      commands.register({
+        name: 'pdf',
+        description: '在侧栏打开 PDF（参数：<路径或文件名片段> [页码]）；默认走 pdf-view 单页跳转模式，页码省略时从第 1 页起',
+        input: { hint: '<PDF 路径或文件名片段> [页码]' },
+        handler: async ({ rawInput }) => {
+          try {
+            const raw = String(rawInput ?? '').trim()
+            if (!raw) return { kind: 'error', text: '用法：/pdf <PDF 路径或文件名片段> [页码]' }
+            const matched = raw.match(/^(.*?)\s+(\d+)$/)
+            const target = matched ? matched[1].trim() : raw
+            const page = matched ? Math.max(1, Math.round(Number(matched[2]))) : 1
+            const pdf = resolvePdf(target, process.cwd(), extraRoots)
+            const port = await ensureViewer()
+            const id = registerFile(pdf)
+            if (config.prefetch !== false) viewer.prefetch(pdf, page)
+            return { kind: 'success', text: `[📄 ${basename(pdf)} · 第 ${page} 页](<http://127.0.0.1:${port}/v/${id}/${page}>)` }
+          } catch (error) {
+            return { kind: 'error', text: error instanceof Error ? error.message : String(error) }
+          }
+        },
+      })
+    }
+  } catch (err) {
+    console.warn(`[dsh-pdf-jump] 未注册 /pdf 命令：${err.message}`)
+  }
+}

package/lib/pdf.mjs

@@ -0,0 +1,236 @@
+/**
+ * PDF 页面渲染：pdfjs-dist 取页 + @napi-rs/canvas 出 PNG。
+ *
+ * 不依赖 Python；首次渲染一个文件时载入文档并缓存，文档改动（mtime/size）后自动重载。
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import { createCanvas } from '@napi-rs/canvas'
+import * as pdfjs from 'pdfjs-dist/legacy/build/pdf.mjs'
+
+const require = createRequire(import.meta.url)
+const PDFJS_ROOT = dirname(require.resolve('pdfjs-dist/package.json')).replaceAll('\\', '/')
+const CMAP_URL = `${PDFJS_ROOT}/cmaps/`
+const STANDARD_FONTS_URL = `${PDFJS_ROOT}/standard_fonts/`
+
+const CACHE_DIR = join(tmpdir(), 'dsh-pdf-jump-cache')
+const MAX_DOCS = 2
+
+const docs = new Map()
+
+class CanvasFactory {
+  create(width, height) {
+    const canvas = createCanvas(Math.max(1, Math.floor(width)), Math.max(1, Math.floor(height)))
+    return { canvas, context: canvas.getContext('2d') }
+  }
+
+  reset({ canvas }, width, height) {
+    canvas.width = Math.max(1, Math.floor(width))
+    canvas.height = Math.max(1, Math.floor(height))
+  }
+
+  destroy() {}
+}
+
+/**
+ * 打开（或复用）一个 PDF 文档。文档句柄连同它的 loading task 一起缓存，
+ * 释放时走 task.destroy()（pdfjs 6 的 PDFDocumentProxy 不再直接提供 destroy）。
+ * @param {string} file PDF 绝对路径
+ */
+async function getDocument(file) {
+  const stat = statSync(file)
+  const hit = docs.get(file)
+  if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) {
+    hit.usedAt = Date.now()
+    return hit.doc
+  }
+  if (hit) {
+    docs.delete(file)
+    await hit.task.destroy().catch(() => {})
+  }
+  const task = pdfjs.getDocument({
+    data: new Uint8Array(readFileSync(file)),
+    isEvalSupported: false,
+    verbosity: 0,
+    useSystemFonts: true,
+    cMapUrl: CMAP_URL,
+    cMapPacked: true,
+    standardFontDataUrl: STANDARD_FONTS_URL,
+    canvasFactory: new CanvasFactory(),
+  })
+  const doc = await task.promise
+  docs.set(file, { doc, task, mtimeMs: stat.mtimeMs, size: stat.size, usedAt: Date.now() })
+  if (docs.size > MAX_DOCS) {
+    const [oldestKey] = [...docs.entries()].sort((a, b) => a[1].usedAt - b[1].usedAt)[0]
+    const oldest = docs.get(oldestKey)
+    docs.delete(oldestKey)
+    await oldest.task.destroy().catch(() => {})
+  }
+  return doc
+}
+
+/**
+ * 页数。页码一律按 PDF 页序，不从页脚推断印刷页码——很多手册混用全书页码和
+ * 「章-页」编号，推断出来的差值会把正文页整体错位。
+ * @param {string} file PDF 绝对路径
+ * @returns {Promise<{pages: number}>}
+ */
+export async function documentInfo(file) {
+  const doc = await getDocument(file)
+  return { pages: doc.numPages }
+}
+
+/**
+ * 清理 7 天前的渲染缓存（只在第一次渲染时执行一次）。
+ */
+let pruned = false
+function pruneCache() {
+  if (pruned) return
+  pruned = true
+  try {
+    const cutoff = Date.now() - 7 * 24 * 3_600_000
+    for (const name of readdirSync(CACHE_DIR)) {
+      const target = join(CACHE_DIR, name)
+      try {
+        if (statSync(target).mtimeMs < cutoff) rmSync(target, { force: true })
+      } catch { /* 单个文件清理失败不影响渲染 */ }
+    }
+  } catch { /* 缓存目录还不存在 */ }
+}
+
+function cachePathFor(file, pdfPage, scale, ext = 'png') {
+  const stat = statSync(file)
+  const key = createHash('md5')
+    .update(`${file}|${stat.mtimeMs}|${stat.size}|${pdfPage}|${scale}`)
+    .digest('hex')
+  return join(CACHE_DIR, `${key}.${ext}`)
+}
+
+/** 整本浏览用的缩略图倍率：0.8 约等于 476px 宽，列表里放大到 760px 内可辨版式。 */
+export const THUMB_SCALE = 0.8
+
+/**
+ * 某页是否已经有渲染缓存（预渲染循环用它跳过已完成的页）。
+ * @param {string} file PDF 绝对路径
+ * @param {number} pdfPage PDF 页序
+ * @param {number} scale 渲染倍率
+ * @returns {boolean}
+ */
+export function isPageCached(file, pdfPage, scale = 2) {
+  try {
+    return existsSync(cachePathFor(file, pdfPage, scale))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * 直接读已渲染的页图；没有缓存返回 null（不触发渲染）。
+ * @param {string} file PDF 绝对路径
+ * @param {number} pdfPage PDF 页序
+ * @param {number} scale 渲染倍率
+ * @returns {Buffer|null}
+ */
+export function readCachedPage(file, pdfPage, scale = 2) {
+  try {
+    const cachePath = cachePathFor(file, pdfPage, scale)
+    return existsSync(cachePath) ? readFileSync(cachePath) : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 把一页渲染成 PNG（带磁盘缓存）。
+ * @param {string} file PDF 绝对路径
+ * @param {number} pdfPage PDF 页序（从 1 起）
+ * @param {number} scale 渲染倍率，2 约等于 144 dpi
+ * @returns {Promise<Buffer>} PNG 字节
+ */
+export async function renderPage(file, pdfPage, scale = 2) {
+  const cachePath = cachePathFor(file, pdfPage, scale)
+  if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true })
+  pruneCache()
+  if (existsSync(cachePath)) return readFileSync(cachePath)
+
+  const doc = await getDocument(file)
+  const page = await doc.getPage(Math.max(1, Math.min(doc.numPages, pdfPage)))
+  const viewport = page.getViewport({ scale })
+  const factory = new CanvasFactory()
+  const { canvas, context } = factory.create(viewport.width, viewport.height)
+  try {
+    await page.render({ canvasContext: context, viewport, canvasFactory: factory }).promise
+    const png = canvas.toBuffer('image/png')
+    writeFileSync(cachePath, png)
+    return png
+  } finally {
+    factory.destroy({ canvas, context })
+  }
+}
+
+/** 缩略图是否已有缓存（整本浏览用，避免重复渲染）。 */
+export function isThumbCached(file, pdfPage, scale = THUMB_SCALE) {
+  try {
+    return existsSync(cachePathFor(file, pdfPage, scale, 'jpg'))
+  } catch {
+    return false
+  }
+}
+
+/** 直接读已渲染的缩略图；没有缓存返回 null。 */
+export function readCachedThumb(file, pdfPage, scale = THUMB_SCALE) {
+  try {
+    const cachePath = cachePathFor(file, pdfPage, scale, 'jpg')
+    return existsSync(cachePath) ? readFileSync(cachePath) : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 把一页渲染成整本浏览用的缩略图（JPEG，白底）。
+ * 缩略图只求版式可辨，编码比全尺寸 PNG 快一个数量级。
+ * @param {string} file PDF 绝对路径
+ * @param {number} pdfPage PDF 页序（从 1 起）
+ * @param {number} scale 倍率，默认 0.8（约 476px 宽）
+ * @param {number} quality JPEG 质量，默认 0.8
+ * @returns {Promise<Buffer>} JPEG 字节
+ */
+export async function renderThumb(file, pdfPage, scale = THUMB_SCALE, quality = 0.8) {
+  const cachePath = cachePathFor(file, pdfPage, scale, 'jpg')
+  if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true })
+  pruneCache()
+  if (existsSync(cachePath)) return readFileSync(cachePath)
+
+  const doc = await getDocument(file)
+  const page = await doc.getPage(Math.max(1, Math.min(doc.numPages, pdfPage)))
+  const viewport = page.getViewport({ scale })
+  const factory = new CanvasFactory()
+  const { canvas, context } = factory.create(viewport.width, viewport.height)
+  try {
+    // JPEG 没有透明通道，先铺白底，和单页查看器的白纸效果一致。
+    context.fillStyle = '#ffffff'
+    context.fillRect(0, 0, canvas.width, canvas.height)
+    await page.render({ canvasContext: context, viewport, canvasFactory: factory }).promise
+    const jpg = canvas.toBuffer('image/jpeg', { quality })
+    writeFileSync(cachePath, jpg)
+    return jpg
+  } finally {
+    factory.destroy({ canvas, context })
+  }
+}
+
+/** 释放所有已载入的文档（插件卸载时调用）。 */
+export async function closeDocuments() {
+  const all = [...docs.values()]
+  docs.clear()
+  await Promise.all(all.map((entry) => entry.task.destroy().catch(() => {})))
+}
+
+/** 渲染缓存目录，供文档与诊断使用。 */
+export const cacheDir = CACHE_DIR