dsh-pdf-jump 0.1.4 → 0.1.6

package/README.en.md

@@ -5,7 +5,7 @@
 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.
+- **`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. It calls `sidebar_open` itself; when the current session has no `sidebar_open` (the third-party sidebar plugin that provides it is not installed, or its "model opens the sidebar" switch is off), it falls back to the `pdf-view` renderer and returns a clickable link (`opened=false`).
 
 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.
 
@@ -35,7 +35,7 @@ After the restart a `/pdf` command is registered as well: `/pdf manual 300` retu
 
 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.
+Requires DSH >= 0.2.1-alpha.3; verified on 0.2.1-alpha.3 and 0.2.2-rc.1, later versions untested.
 
 ## Use
 
@@ -47,13 +47,13 @@ Compatible with the DSH 0.2.1 line (alpha / rc / stable); 0.3 and later are not
 | 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.
+Both tools accept an absolute/relative path or a file-name fragment; relative paths resolve against the session working directory. Results are one clickable document line: `pdf-open` calls `sidebar_open` for the native preview (or falls back to the viewer link), `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-open` resolves the path and calls `sidebar_open` (when the session has it) for the native preview; without `sidebar_open` it falls back to a `pdf-view` viewer link.
 - `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.
+- `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. Page images and thumbnails carry a 1-hour browser cache, so flipping back and forth does not re-download them.
 - 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.
@@ -63,18 +63,6 @@ Both tools accept an absolute/relative path or a file-name fragment (for example
 
 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 |
 | --- | --- | --- |
@@ -89,7 +77,7 @@ Optional, in the profile patch row (affects `pdf-view` only):
 
 ## Limitations
 
-- `pdf-open` relies on DSH's built-in PDF preview; use the default `pdf-view` where that preview is absent.
+- `pdf-open`'s native preview needs a sidebar plugin that registers the `sidebar_open` tool; that feature is off by default and must be enabled in its settings ("model opens the sidebar"). Without it, `pdf-open` falls back to the `pdf-view` renderer; no third-party plugin is needed just to read PDFs.
 - `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.
 

package/README.md

@@ -5,7 +5,7 @@
 在 DSH 侧栏里看本地 PDF。一个包装两个独立工具，装一次两个都可用：
 
 - **`pdf-view`（默认入口）**：本地把页面渲染成图——**按页码跳**、**整本浏览**；整本页先出缩略图、滚到哪页换高清，页顶还能输入页码直接跳。不依赖原生预览，任何 profile 都能用。
-- **`pdf-open`**：用 DSH **原生的 PDF 预览**打开（客户端直接渲染，不生成图片、不起本地服务、有文字层）；只在明确要「原生预览、不生成图片、最快」时用。
+- **`pdf-open`**：用 DSH **原生的 PDF 预览**打开（客户端直接渲染，不生成图片、不起本地服务、有文字层）；只在明确要「原生预览、不生成图片、最快」时用。它会自己调 `sidebar_open`；本会话没有 `sidebar_open`（提供它的第三方侧栏插件未装，或它的「模型打开侧栏」开关没开）时，自动回落到 `pdf-view` 的渲染查看器，返回可点的链接（`opened=false`）。
 
 页码按 **PDF 页序**（1 = 文件第一页）。不从页脚推断印刷页码：手册常把全书页码和「章-页」编号混着用，猜出来的差值会把正文页整体错位。
 
@@ -35,7 +35,7 @@ dsh plugin --profile web add github:taoziliyouchong/dsh-pdf-jump
 
 要求：DSH 带宿主 `tools` 与 `systemPrompt` 服务（普通基础组合都含），Node 22.19+ 或 24+。
 
-兼容：DSH 0.2.1 系列（alpha / rc / 正式版均可）；0.3 起不保证。
+要求 DSH >= 0.2.1-alpha.3；实测 0.2.1-alpha.3、0.2.2-rc.1，更高版本未验证。
 
 ## 用法
 
@@ -47,13 +47,14 @@ dsh plugin --profile web add github:taoziliyouchong/dsh-pdf-jump
 | 不让模型判断、直接开 | `/pdf <文件或片段> [页码]` |
 | 提取文字 / 读元数据 | 另装 `dsh-pdf` 插件，用它的 `pdf_info` / `pdf_extract_text` |
 
-两个工具都接受绝对/相对路径或文件名片段（如 `NB系列 安装手册`）；相对路径按会话工作目录解析。结果都会显示成一条可点的文档行，`pdf-open` 指向文件本身（由侧栏原生预览打开），`pdf-view` 指向本地查看页。
+两个工具都接受绝对/相对路径或文件名片段（如 `NB系列 安装手册`）；相对路径按会话工作目录解析。结果都会显示成一条可点的文档行，`pdf-open` 自己调 `sidebar_open` 用原生预览打开（没有它时回落到查看器链接），`pdf-view` 指向本地查看页。
 
 ## 机制
 
-- `pdf-open` 只解析路径并返回文件路径，交给 `sidebar_open`；渲染完全由 DSH 客户端完成。
+- `pdf-open` 解析路径后直接调 `sidebar_open`（若本会话有）用原生预览打开；没有 `sidebar_open` 时自动回落到 `pdf-view` 的查看器链接。
 - `pdf-view` 的本地 HTTP 服务只绑 `127.0.0.1`，端口从 8731 往上试，复用别的 DSH 进程已起的服务；插件一加载就启动，整个 DSH 会话期间常驻（`idleMinutes: 0`），旧对话里的链接不用重新生成。
-- `pdf-view` 用 `pdfjs-dist` + `@napi-rs/canvas` 把页面渲成 PNG 缓存在系统临时目录；工具一调用先暖请求页和前后各 2 页，打开后以当前页为中心向两边各暖 6 页，已缓存的页直接读盘、不进渲染队列。
+- `pdf-view` 用 `pdfjs-dist` + `@napi-rs/canvas` 把页面渲成 PNG 缓存在系统临时目录；工具一调用先暖请求页和前后各 2 页，打开后以当前页为中心向两边各暖 6 页，已缓存的页直接读盘、不进渲染队列。页图与缩略图带 1 小时浏览器缓存，来回翻页不重复下载。
+- 渲染在**子进程**里做（`lib/render-child.mjs`，一页一进程）：同一个宿主里若还有别的插件带不同版本的 pdf.js，后写的那份会把 `globalThis.pdfjsWorker` 换成自己的，同进程混合会报「API version … does not match Worker version …」。子进程有自己的 module graph 与全局，互不影响；代价是每页首次渲染多 0.3–0.8 秒。
 - 整本浏览先用 0.8 倍 JPEG 缩略图铺满（每页十几毫秒），滚到哪页再把那页换成全尺寸 PNG；每一页都有锚点（`#p40`），整本页顶部输入页码即滚到该页。
 - `/pdf` 命令固定走 `pdf-view`（单页跳转模式），不带页码时从第 1 页起；要原生预览就直接调 `pdf-open`，或说「原生预览打开」。
 - 查看地址是短路径（`/v/<id>/<页>`、`/d/<id>`、`/p/<id>/<页>.png`、`/t/<id>/<页>.jpg`），不带查询串；id 通过系统临时目录里的小注册表映射到文件。配合「插件加载即启动、端口固定」，DSH 重启后旧对话里的链接也能重新打开。
@@ -61,20 +62,8 @@ dsh plugin --profile web add github:taoziliyouchong/dsh-pdf-jump
 
 ## 配置
 
-可选，写在 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
-```
+可选，写在 profile 的 patch 行里（只影响 `pdf-view`）；字段与默认值：
+
 
 | 字段 | 默认 | 含义 |
 | --- | --- | --- |
@@ -89,7 +78,7 @@ dsh plugin --profile web add github:taoziliyouchong/dsh-pdf-jump
 
 ## 限制
 
-- `pdf-open` 依赖 DSH 自带的原生 PDF 预览；没有该预览的环境用默认的 `pdf-view`。
+- `pdf-open` 的原生预览依赖一个提供 `sidebar_open` 工具的侧栏插件（如 dsh-better-sidebar），且该功能默认关闭、需要在它的设置里打开「模型打开侧栏」。没有它时 `pdf-open` 自动回落到 `pdf-view` 的渲染查看器；只想看 PDF 的话不装任何第三方也能用。
 - `pdf-view` 的页面是图片：不能选文字，也不能全文搜索；要文字另装 `dsh-pdf` 插件，用它的 `pdf_extract_text`。
 - 渲染依赖 `@napi-rs/canvas` 的预编译二进制，覆盖 Windows / macOS / Linux 的 x64 与 arm64。
 

package/index.js

@@ -24,11 +24,14 @@ const FEEDBACK_HINT = '遇到问题：加 QQ 号 2171960697，或开 Issue https
  */
 const GUIDANCE = [
   '本机装了 dsh-pdf-jump（在侧栏里看 PDF，两个独立入口）：',
+  '- 硬规则：凡是跟 PDF 有关的答复——打开、翻页、读手册某章、按页查内容、提取文字、比对字体——第一步调 pdf-view 打开相关页，并把页链接给用户。只贴文字、只渲染图片、只给摘录，都算没做完。',
   '- 默认用 pdf-view（单页跳转模式）：带页码打开，页面带「上一页/下一页/跳页码/整本浏览」。用户只说「打开/看一眼某本 PDF」「打开第 N 页」也一律用它。',
+  '- 还不知道页码时：先用 dsh-pdf 的 pdf_info / pdf_extract_text（或 doc-probe-search）定位页码，再立刻用 pdf-view 跳到该页。',
+  '- 用户说「放到对应的页」「给我看第 N 页」时：必须给 pdf-view 的页链接，不许用图片或摘录替代。',
   '- pdf-open 只在明确要求「原生预览、不生成图片、最快」时才用，不作为默认。',
-  '- 用户要提取 PDF 文字、读元数据或比较字体时，用 dsh-pdf 插件（需另装）的 pdf_info / pdf_extract_text，不要用这两个工具。',
-  '- 不要绕过这两个工具自己用 sidebar_open 打开 PDF 文件：那样没有跳页、没有整本浏览；pdf-open 返回的路径再交给 sidebar_open 才是正确顺序。',
-  '- 两个工具都返回本机路径或本地 url：有 sidebar_open 就先调它开在侧栏；不要把裸路径/裸 url 贴给用户，用「📄 文件名」做链接文字。',
+  '- dsh-pdf 的 pdf_info / pdf_extract_text 只用于取页码、取文字、读元数据、比字体；取完仍要给 pdf-view 页链接。',
+  '- 不要绕过这两个工具自己用 sidebar_open 打开 PDF 文件：那样没有跳页、没有整本浏览。pdf-open 会自己调 sidebar_open 用原生预览打开——本会话没有 sidebar_open（第三方侧栏插件没装、或它的「模型打开侧栏」开关没开）时，它会回落到 pdf-view 的渲染查看器并给一个可点的链接。',
+  '- 两个工具都返回本机路径或本地 url：不要把裸路径/裸 url 贴给用户，用「📄 文件名」做链接文字。pdf-view 的 url 要 sidebar_open 打开才落到侧栏；没有 sidebar_open 时直接在回复里给可点的链接。',
   '- 只给了文件名片段、不知道路径时直接传进去：先按会话工作目录找，再按片段搜。',
   '- 用户说「点了链接没反应 / 打不开」时，说明是侧栏浏览器默认拦截本机地址：建议把「网页链接默认打开方式」改成默认浏览器，或把 127.0.0.1:<端口> 加进侧栏设置里的本机地址白名单。',
   '- 旧对话里的 url 在服务空闲退出后会失效，不要复用；每次重新调用取新地址。',
@@ -63,12 +66,15 @@ const output = {
 }
 
 /** 当前会话的工作目录；取不到时退回进程目录。 */
-function sessionCwd(ctx, exec) {
+async function sessionCwd(ctx, exec) {
   try {
     const workingDirectory = ctx.get?.('workingDirectory')
-    const session = exec?.agent?.session
-    if (workingDirectory && session) return workingDirectory.get(session)
-  } catch { /* 老版本没有这个服务，用进程目录 */ }
+    if (workingDirectory && exec?.agent) {
+      // ensure() 按 Agent 取会话目录（get() 要的是 Session 对象，工具上下文只有 Agent）。
+      return await workingDirectory.ensure(exec.agent, exec?.signal)
+    }
+    if (workingDirectory?.defaultDirectory) return workingDirectory.defaultDirectory
+  } catch { /* 服务不可用或目录已被删除，用进程目录 */ }
   return process.cwd()
 }
 
@@ -117,10 +123,13 @@ export function apply(ctx, config = {}) {
         output,
         isConcurrencySafe: () => true,
         async execute(args, exec) {
-          const cwd = args.cwd ? resolve(String(args.cwd)) : sessionCwd(ctx, exec)
+          const cwd = args.cwd ? resolve(String(args.cwd)) : await 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 requested = Math.max(1, Math.round(Number(args.page) || 1))
+          // 超出总页数时钳到最后一页——和查看器里显示的一致，返回文案不报一个看不到的页码。
+          const total = await viewer.pageCount(pdf).catch(() => 0)
+          const page = total > 0 ? Math.min(total, requested) : requested
           const id = registerFile(pdf)
           // 工具一返回就在后台把这一页和附近几页渲进缓存，用户点开时直接取图。
           if (config.prefetch !== false) viewer.prefetch(pdf, page)
@@ -156,9 +165,11 @@ export function apply(ctx, config = {}) {
             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 requested = matched ? Math.max(1, Math.round(Number(matched[2]))) : 1
             const pdf = resolvePdf(target, process.cwd(), extraRoots)
             const port = await ensureViewer()
+            const total = await viewer.pageCount(pdf).catch(() => 0)
+            const page = total > 0 ? Math.min(total, requested) : requested
             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}>)` }

package/lib/pdf.mjs

@@ -1,77 +1,89 @@
 /**
- * PDF 页面渲染：pdfjs-dist 取页 + @napi-rs/canvas 出 PNG。
+ * PDF 页面渲染：**在子进程里**用 pdfjs-dist 取页、@napi-rs/canvas 出图，宿主进程只负责调度与缓存。
  *
- * 不依赖 Python；首次渲染一个文件时载入文档并缓存，文档改动（mtime/size）后自动重载。
+ * 为什么隔进程：pdfjs 通过 globalThis.pdfjsWorker.WorkerMessageHandler 找 worker。
+ * 宿主里只要还有另一个插件带不同版本的 pdfjs（例如 4.10.38），后写的会把全局改成自己的，
+ * 本插件 6.x 的 API 就会拿到 4.x 的 worker，渲染直接失败
+ * （「API version 6.4.299 does not match Worker version 4.10.38」）。
+ * 子进程有自己的 module graph 与全局，版本永远不会被别的插件换掉。
+ *
+ * 代价：每页首次渲染多一次进程启动（约 0.3–0.8 秒）；出图后落磁盘缓存，翻过的页不再付。
  */
-
-import { createHash } from 'node:crypto'
+import { spawn } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
-import { createRequire } from 'node:module'
+import { createHash } from 'node:crypto'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
 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 CHILD = fileURLToPath(new URL('./render-child.mjs', import.meta.url))
 const CACHE_DIR = join(tmpdir(), 'dsh-pdf-jump-cache')
-const MAX_DOCS = 2
+const MAX_CHILDREN = 2
 
-const docs = new Map()
+/** 子进程并发闸门：缩略图会连着请求，不设上限会一次拉起几十个进程。 */
+let running = 0
+const waiting = []
 
-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))
+function acquire() {
+  if (running < MAX_CHILDREN) {
+    running += 1
+    return Promise.resolve()
   }
+  return new Promise((resolve) => waiting.push(resolve))
+}
 
-  destroy() {}
+function release() {
+  const next = waiting.shift()
+  if (next) next()
+  else running -= 1
 }
 
 /**
- * 打开（或复用）一个 PDF 文档。文档句柄连同它的 loading task 一起缓存，
- * 释放时走 task.destroy()（pdfjs 6 的 PDFDocumentProxy 不再直接提供 destroy）。
- * @param {string} file PDF 绝对路径
+ * 跑一次渲染子进程。
+ * @param {string[]} args 子进程参数
+ * @returns {Promise<{stdout: string, stderr: string}>}
  */
-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(() => {})
+async function runChild(args) {
+  await acquire()
+  try {
+    return await new Promise((resolve, reject) => {
+      // 宿主是 Electron：process.execPath 是 exe，要靠 ELECTRON_RUN_AS_NODE 才按 Node 跑脚本。
+      const env = { ...process.env, ELECTRON_RUN_AS_NODE: '1' }
+      const child = spawn(process.execPath, [CHILD, ...args], { env, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] })
+      let stdout = ''
+      let stderr = ''
+      child.stdout.setEncoding('utf8')
+      child.stderr.setEncoding('utf8')
+      child.stdout.on('data', (chunk) => { stdout += chunk })
+      child.stderr.on('data', (chunk) => { stderr += chunk })
+      const timer = setTimeout(() => {
+        child.kill()
+        reject(new Error('渲染超时（子进程没有在 60 秒内返回）'))
+      }, 60_000)
+      child.once('error', (error) => {
+        clearTimeout(timer)
+        reject(error)
+      })
+      child.once('close', (code) => {
+        clearTimeout(timer)
+        if (code === 0) resolve({ stdout, stderr })
+        else reject(new Error((stderr || stdout || `渲染子进程退出码 ${code}`).trim().slice(0, 400)))
+      })
+    })
+  } finally {
+    release()
   }
-  return doc
+}
+
+/** 页数缓存：{ pages, mtimeMs, size }，文件变了就重新问。 */
+const infoCache = new Map()
+
+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}`)
 }
 
 /**
@@ -81,8 +93,14 @@ async function getDocument(file) {
  * @returns {Promise<{pages: number}>}
  */
 export async function documentInfo(file) {
-  const doc = await getDocument(file)
-  return { pages: doc.numPages }
+  const stat = statSync(file)
+  const hit = infoCache.get(file)
+  if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) return { pages: hit.pages }
+  const { stdout } = await runChild(['--info', '--file', file])
+  const pages = Number(JSON.parse(stdout.trim()).pages)
+  if (!Number.isFinite(pages) || pages < 1) throw new Error('读取页数失败')
+  infoCache.set(file, { pages, mtimeMs: stat.mtimeMs, size: stat.size })
+  return { pages }
 }
 
 /**
@@ -103,14 +121,6 @@ function pruneCache() {
   } 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
 
@@ -153,24 +163,12 @@ export function readCachedPage(file, pdfPage, scale = 2) {
  * @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()
+  const cachePath = cachePathFor(file, pdfPage, scale)
   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 })
-  }
+  await runChild(['--file', file, '--page', String(pdfPage), '--scale', String(scale), '--format', 'png', '--out', cachePath])
+  return readFileSync(cachePath)
 }
 
 /** 缩略图是否已有缓存（整本浏览用，避免重复渲染）。 */
@@ -202,34 +200,20 @@ export function readCachedThumb(file, pdfPage, scale = THUMB_SCALE) {
  * @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()
+  const cachePath = cachePathFor(file, pdfPage, scale, 'jpg')
   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 })
-  }
+  await runChild(['--file', file, '--page', String(pdfPage), '--scale', String(scale), '--format', 'jpg', '--quality', String(quality), '--out', cachePath])
+  return readFileSync(cachePath)
 }
 
-/** 释放所有已载入的文档（插件卸载时调用）。 */
+/**
+ * 释放资源。渲染在子进程里做，宿主侧没有常驻文档；这里保留接口给调用方，
+ * 顺便清掉页数缓存。
+ */
 export async function closeDocuments() {
-  const all = [...docs.values()]
-  docs.clear()
-  await Promise.all(all.map((entry) => entry.task.destroy().catch(() => {})))
+  infoCache.clear()
 }
 
 /** 渲染缓存目录，供文档与诊断使用。 */

package/lib/render-child.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * 单页渲染子进程：一页一进程，渲染完就退出。
+ *
+ * 为什么不在宿主进程里直接渲染：pdfjs 用它挂在 globalThis 上的
+ * `pdfjsWorker.WorkerMessageHandler` 找 worker；宿主里如果还有别的插件带另一个
+ * pdfjs 版本（比如 4.10.38），后写的那份会把全局改成自己的，于是本插件 6.x 的
+ * API 拿到 4.x 的 worker，报「API version 6.4.299 does not match Worker version 4.10.38」。
+ * 子进程有自己的 module graph 和全局，谁也不影响谁。
+ *
+ * 用法：
+ *   node render-child.mjs --info --file <pdf>
+ *   node render-child.mjs --file <pdf> --page <n> --scale <s> --out <png/jpg> [--format png|jpg] [--quality 0.8]
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname } 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 argv = process.argv.slice(2)
+const flag = (name) => argv.includes(name)
+const opt = (name, fallback) => {
+  const at = argv.indexOf(name)
+  return at >= 0 && at + 1 < argv.length ? argv[at + 1] : fallback
+}
+
+const file = opt('--file')
+if (!file) {
+  console.error('render-child: 缺少 --file')
+  process.exit(2)
+}
+
+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() {}
+}
+
+function open() {
+  return pdfjs.getDocument({
+    data: new Uint8Array(readFileSync(file)),
+    isEvalSupported: false,
+    verbosity: 0,
+    useSystemFonts: true,
+    cMapUrl: `${PDFJS_ROOT}/cmaps/`,
+    cMapPacked: true,
+    standardFontDataUrl: `${PDFJS_ROOT}/standard_fonts/`,
+    canvasFactory: new CanvasFactory(),
+  })
+}
+
+try {
+  const task = open()
+  const doc = await task.promise
+  if (flag('--info')) {
+    process.stdout.write(JSON.stringify({ pages: doc.numPages }) + '\n')
+    await task.destroy().catch(() => {})
+    process.exit(0)
+  }
+
+  const pageNo = Math.max(1, Math.min(doc.numPages, Number(opt('--page', '1')) || 1))
+  const scale = Number(opt('--scale', '2')) || 2
+  const format = opt('--format', 'png') === 'jpg' ? 'jpg' : 'png'
+  const quality = Number(opt('--quality', '0.8')) || 0.8
+  const out = opt('--out')
+  if (!out) {
+    console.error('render-child: 缺少 --out')
+    process.exit(2)
+  }
+
+  const page = await doc.getPage(pageNo)
+  const viewport = page.getViewport({ scale })
+  const factory = new CanvasFactory()
+  const { canvas, context } = factory.create(viewport.width, viewport.height)
+  try {
+    // JPEG 没有透明通道，先铺白底，和单页查看器的白纸效果一致。
+    if (format === 'jpg') {
+      context.fillStyle = '#ffffff'
+      context.fillRect(0, 0, canvas.width, canvas.height)
+    }
+    await page.render({ canvasContext: context, viewport, canvasFactory: factory }).promise
+    const bytes = format === 'jpg'
+      ? canvas.toBuffer('image/jpeg', { quality })
+      : canvas.toBuffer('image/png')
+    writeFileSync(out, bytes)
+    process.stdout.write(JSON.stringify({ pages: doc.numPages, bytes: bytes.length }) + '\n')
+  } finally {
+    factory.destroy({ canvas, context })
+  }
+  await task.destroy().catch(() => {})
+  process.exit(0)
+} catch (error) {
+  console.error(String(error && error.message || error))
+  process.exit(1)
+}

package/lib/resolve.mjs

@@ -2,17 +2,64 @@
  * 把工具参数 file 落成一个真实存在的 PDF 路径。
  *
  * 优先按路径解析（相对路径按调用方给的工作目录）；找不到时把 file 当文件名片段，
- * 在搜索根里广度优先找（浅层优先，带数量与时间上限）。
+ * 在搜索根里广度优先找（浅层优先，带数量与时间上限）。搜索根默认是会话工作目录，
+ * 再加上用户主目录下常见的桌面 / 文档 / 下载——只给片段时桌面上的 PDF 也能找到。
  */
 
+import { execFileSync } from 'node:child_process'
 import { existsSync, readdirSync, statSync } from 'node:fs'
-import { delimiter, basename, join, resolve } from 'node:path'
+import { homedir } from 'node:os'
+import { delimiter, basename, isAbsolute, join, resolve } from 'node:path'
 
 const SKIP_DIRS = new Set([
   'node_modules', '.git', '.pnpm', '_backup', '$RECYCLE.BIN',
   'System Volume Information', '.cache', '__pycache__',
 ])
 
+const SHELL_FOLDERS_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders'
+
+/** 读 Windows 已知文件夹的真实路径（桌面可能被重定向到别的盘）。 */
+function readShellFolder(name) {
+  try {
+    // reg.exe 按系统 OEM 代码页输出（中文 Windows 是 GBK），不能按 UTF-8 解码。
+    const raw = execFileSync('reg', ['query', SHELL_FOLDERS_KEY, '/v', name], {
+      timeout: 1500, windowsHide: true,
+    })
+    let text
+    try {
+      text = new TextDecoder('gbk').decode(raw)
+    } catch {
+      text = raw.toString('utf8')
+    }
+    const match = text.match(/REG_(?:EXPAND_)?SZ\s+(.+?)\s*$/m)
+    if (!match) return null
+    return match[1].replace(/%([^%]+)%/g, (_, key) => process.env[key] ?? '')
+  } catch {
+    return null
+  }
+}
+
+let cachedHomeRoots
+
+/** 用户主目录下常见的几处（桌面 / 文档 / 下载，按系统实际路径，存在才收）。 */
+function homeRoots() {
+  if (cachedHomeRoots) return cachedHomeRoots
+  const home = homedir()
+  const onWindows = process.platform === 'win32'
+  const roots = [
+    (onWindows && readShellFolder('Desktop')) || join(home, 'Desktop'),
+    (onWindows && readShellFolder('Personal')) || join(home, 'Documents'),
+    (onWindows && readShellFolder('{374DE290-123F-4565-9164-39C4925E467B}')) || join(home, 'Downloads'),
+  ]
+  cachedHomeRoots = roots.filter(Boolean)
+  return cachedHomeRoots
+}
+
+/** Windows 盘符路径 / UNC 路径都算绝对路径（path.isAbsolute 认前者，不认 UNC 的写法差异）。 */
+function isAbsolutePath(raw) {
+  return isAbsolute(raw) || /^[a-zA-Z]:[\\/]/.test(raw) || /^\\\\/.test(raw)
+}
+
 /**
  * @param {string} root 搜索根
  * @param {number} limit 最多收多少个 PDF
@@ -34,7 +81,9 @@ export function collectPdfs(root, limit = 20000, budgetMs = 8000) {
     for (const entry of entries) {
       const full = join(queue[i], entry.name)
       if (entry.isDirectory()) {
-        if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) continue
+        // 只跳过确定没有 PDF 的大目录；隐藏目录（如 .build）不再一律跳过——
+        // 构建产物里也可能放 PDF。
+        if (SKIP_DIRS.has(entry.name)) continue
         queue.push(full)
       } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.pdf')) {
         out.push(full)
@@ -56,18 +105,24 @@ export function resolvePdf(input, cwd, extraRoots = []) {
   if (!raw) throw new Error('file 不能为空')
   const direct = resolve(cwd, raw)
   if (existsSync(direct) && statSync(direct).isFile()) return direct
+  // 绝对路径不存在就是不存在，不再按片段去扫目录，错误信息也不带搜索根噪音。
+  if (isAbsolutePath(raw)) throw new Error(`文件不存在：${raw}`)
 
   const needle = basename(raw).toLowerCase()
   const roots = [...extraRoots.filter(Boolean)]
   const envRoots = process.env.PDF_JUMP_ROOTS
   if (envRoots) roots.push(...envRoots.split(delimiter).filter(Boolean))
   roots.push(cwd)
+  roots.push(...homeRoots())
   const seen = new Set()
+  const base = resolve(cwd)
   for (const root of roots) {
     const abs = resolve(root)
     if (seen.has(abs) || !existsSync(abs)) continue
     seen.add(abs)
-    const hits = collectPdfs(abs)
+    // 工作目录优先，额度给足；桌面 / 文档 / 下载是兜底，限时短一些。
+    const budgetMs = abs === base ? 8000 : 4000
+    const hits = collectPdfs(abs, 20000, budgetMs)
       .filter((file) => basename(file).toLowerCase().includes(needle))
       .sort((a, b) => a.length - b.length)
     if (hits.length > 0) return hits[0]

package/lib/server.mjs

@@ -210,6 +210,63 @@ document.addEventListener('keydown', (e) => {
 </script></body></html>`
 }
 
+/**
+ * 渲染/读取失败时给人看的说明页。白屏和裸报错都等于没说清原因，
+ * 所以这里按错误内容给「原因 + 怎么办」，原始错误折叠在下面备查。
+ */
+function buildErrorHtml({ file, printed, message }) {
+  const raw = String(message || '未知错误')
+  const name = String(file || '').replace(/^.*[\\/]/, '')
+  const cause = /does not match the Worker version/i.test(raw)
+    ? {
+      title: '渲染库版本冲突',
+      why: '这台 DSH 里还有另一个插件带着不同版本的 pdf.js。两个版本在同一个进程里共用「渲染器」登记位，后加载的那份会把它改写成自己的版本，本插件再渲染时两边版本对不上。',
+      todo: '重启 DSH（新版已把渲染挪到独立进程，重启后不会再撞）。重启后仍报这句，就把下面的原始错误一起发出来。',
+    }
+    : /ENOENT|no such file|cannot find|找不到/i.test(raw)
+      ? {
+        title: '文件不在了或读不了',
+        why: '按这个路径找不到 PDF，或者当前用户没有读权限。',
+        todo: '确认文件还在原位置；被移动过就重新用 pdf-view 打开一次。',
+      }
+      : /超时|timeout/i.test(raw)
+        ? {
+          title: '渲染超时',
+          why: '这一页在 60 秒内没渲染完，通常是大页面或字体缺失拖慢的。',
+          todo: '点「重试」再翻一次；连续失败把下面的原始错误发出来。',
+        }
+        : {
+          title: '这一页没渲染出来',
+          why: '渲染进程返回了错误。',
+          todo: '点「重试」；还在失败就把下面的原始错误发出来。',
+        }
+  return `<!doctype html><html lang="zh"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(name)} · 渲染失败</title>
+<style>
+:root{color-scheme:light dark}
+*{box-sizing:border-box}
+body{margin:0;min-height:100%;background:#2b2b2b;color:#ddd;font:14px/1.6 system-ui,-apple-system,"Segoe UI",sans-serif;padding:28px 22px}
+.card{max-width:720px;margin:0 auto;background:#242424;border:1px solid #3a3a3a;border-radius:10px;padding:18px 20px}
+h1{font-size:16px;margin:0 0 10px;color:#ffb4b4}
+.meta{opacity:.65;font-size:12px;margin-bottom:14px}
+h2{font-size:13px;margin:16px 0 4px;color:#8cc4ff;font-weight:600}
+p{margin:0;white-space:pre-wrap}
+details{margin-top:16px;border-top:1px dashed #3a3a3a;padding-top:10px}
+summary{cursor:pointer;opacity:.75;font-size:12px}
+code{display:block;margin-top:8px;padding:8px 10px;border-radius:6px;background:#111;color:#ffc9c9;font:12px/1.5 ui-monospace,Consolas,monospace;white-space:pre-wrap;word-break:break-all}
+button{margin-top:16px;height:32px;padding:0 14px;border:1px solid #4a4a4a;border-radius:6px;background:#333;color:#eee;font:inherit;cursor:pointer}
+button:hover{background:#414141}
+</style></head><body><div class="card">
+<h1>${escapeHtml(cause.title)}</h1>
+<div class="meta">${escapeHtml(name)}${printed ? ` · 第 ${printed} 页` : ''}</div>
+<h2>原因</h2><p>${escapeHtml(cause.why)}</p>
+<h2>怎么办</h2><p>${escapeHtml(cause.todo)}</p>
+<details><summary>原始错误</summary><code>${escapeHtml(raw)}</code></details>
+<button onclick="location.reload()">重试</button>
+</div></body></html>`
+}
+
 /**
  * 整本浏览页：先用缩略图铺满（每页十几毫秒），滚到哪页再把那页换成全尺寸。
  * 点某页进单页查看器；全部在侧栏里完成，不打开外部浏览器。
@@ -455,13 +512,13 @@ export function createViewer(options = {}) {
         const page = Math.max(1, Math.min(total, n))
         const cached = readCachedThumb(file, page)
         if (cached) {
-          send(res, 200, 'image/jpeg', cached)
+          send(res, 200, 'image/jpeg', cached, { 'Cache-Control': 'public, max-age=3600' })
           return
         }
         const jpg = await schedule(() => renderThumb(file, page), 15)
-        send(res, 200, 'image/jpeg', jpg)
+        send(res, 200, 'image/jpeg', jpg, { 'Cache-Control': 'public, max-age=3600' })
       } catch (err) {
-        send(res, 500, 'text/plain; charset=utf-8', String(err && err.message ? err.message : err))
+        send(res, 500, 'text/html; charset=utf-8', buildErrorHtml({ file, printed, message: err && err.message ? err.message : err }))
       }
       return
     }
@@ -476,7 +533,7 @@ export function createViewer(options = {}) {
         const total = await pagesOf(file)
         send(res, 200, 'text/html; charset=utf-8', buildDocumentHtml({ id, file, total }))
       } catch (err) {
-        send(res, 500, 'text/plain; charset=utf-8', String(err && err.message ? err.message : err))
+        send(res, 500, 'text/html; charset=utf-8', buildErrorHtml({ file, printed, message: err && err.message ? err.message : err }))
       }
       return
     }
@@ -488,7 +545,7 @@ export function createViewer(options = {}) {
         warmAround(file, page, prefetchWindow)
         send(res, 200, 'text/html; charset=utf-8', buildHtml({ id, file, printed: page, total, pdfPage: page }))
       } catch (err) {
-        send(res, 500, 'text/plain; charset=utf-8', String(err && err.message ? err.message : err))
+        send(res, 500, 'text/html; charset=utf-8', buildErrorHtml({ file, printed, message: err && err.message ? err.message : err }))
       }
       return
     }
@@ -497,11 +554,11 @@ export function createViewer(options = {}) {
     warmAround(file, printed, prefetchWindow)
     const cached = readCachedPage(file, printed, scale)
     if (cached) {
-      send(res, 200, 'image/png', cached)
+      send(res, 200, 'image/png', cached, { 'Cache-Control': 'public, max-age=3600' })
       return
     }
     schedule(() => renderPage(file, printed, scale), 10)
-      .then((pngData) => { if (!res.headersSent) send(res, 200, 'image/png', pngData) })
+      .then((pngData) => { if (!res.headersSent) send(res, 200, 'image/png', pngData, { 'Cache-Control': 'public, max-age=3600' }) })
       .catch((err) => { if (!res.headersSent) send(res, 500, 'text/plain; charset=utf-8', String(err)) })
   }
 
@@ -564,6 +621,8 @@ export function createViewer(options = {}) {
   return {
     start,
     stop,
+    /** 页数（与查看器同一份缓存）；工具层用它把超出范围的页码钳到最后一页。 */
+    pageCount: (file) => pagesOf(file),
     prefetch: (file, page) => warmAround(file, page, Math.min(2, prefetchWindow)),
     get port() { return port },
     get owned() { return owned },

package/native.js

@@ -1,11 +1,16 @@
 /**
- * 类型：工具；解决：只想「打开看一眼」PDF 时不应走图片渲染；作用：返回本地 PDF 路径，
- * 交给 sidebar_open 用 DSH 原生 PDF 预览打开（客户端渲染，最快）。
+ * 类型：工具；解决：只想「打开看一眼」PDF 时不应走图片渲染；作用：直接调 sidebar_open
+ * 用 DSH 原生 PDF 预览打开（客户端渲染，最快）；本会话没有 sidebar_open 时回落到
+ * pdf-view 的渲染查看器，给出可点的链接。
+ *
+ * sidebar_open 是第三方侧栏插件（dsh-better-sidebar）提供的工具，而且默认关闭；
+ * 别的会话里未必存在，所以这里不假定它一定在。
  */
 
 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-native'
@@ -28,26 +33,65 @@ const output = {
     properties: {
       ok: { type: 'boolean' },
       file: { type: 'string' },
+      opened: { type: 'boolean' },
+      url: { type: 'string' },
     },
-    required: ['ok', 'file'],
+    required: ['ok', 'file', 'opened'],
   },
   render: (_args, value) => [{
     type: 'text',
-    text: `[📄 ${basename(value.file)}](<${value.file}>)`,
+    text: value.opened
+      ? `[📄 ${basename(value.file)}](<${value.file}>) · 已用原生预览请求在侧栏打开`
+      : `本会话没有可用的 sidebar_open（第三方侧栏插件未装，或它的「模型打开侧栏」开关没开），已回落到渲染查看器：[📄 ${basename(value.file)}](<${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 { /* 老版本没有这个服务，用进程目录 */ }
+    if (workingDirectory && exec?.agent?.id) {
+      // ensure() 按 Agent 取会话目录；它是异步的，调用方 await。
+      return Promise.resolve(workingDirectory.ensure(exec.agent, exec?.signal)).catch(() => process.cwd())
+    }
+    if (workingDirectory?.defaultDirectory) return workingDirectory.defaultDirectory
+  } catch { /* 服务不可用或目录已被删除，用进程目录 */ }
   return process.cwd()
 }
 
+/**
+ * 调 sidebar_open 把 PDF 在侧栏用原生预览打开。
+ * 工具不存在（第三方插件未装 / 开关没开）或调用失败都返回 false，交给调用方回落。
+ */
+async function openInSidebar(ctx, exec, pdf) {
+  try {
+    if (typeof ctx.tools.get !== 'function' || typeof ctx.tools.execute !== 'function') return false
+    if (!ctx.tools.get('sidebar_open', exec?.agent)) return false
+    const result = await ctx.tools.execute({
+      callId: `pdf-open-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      name: 'sidebar_open',
+      arguments: { target: pdf, title: basename(pdf) },
+      signal: exec?.signal ?? new AbortController().signal,
+      ...(exec?.agent ? { agent: exec.agent } : {}),
+      ...(exec?.token ? { parent: exec.token } : {}),
+    })
+    return result?.isError !== true
+  } catch {
+    return false
+  }
+}
+
 export function apply(ctx, config = {}) {
   const extraRoots = Array.isArray(config.roots) ? config.roots.map(String) : []
+  // 只在需要回落时启动；index.js 那半边通常已经把同端口的服务拉起来了，start() 会复用它。
+  const viewer = createViewer({
+    port: config.port,
+    scale: config.scale,
+    idleMinutes: config.idleMinutes,
+    prefetch: config.prefetch,
+    prefetchWindow: config.prefetchWindow,
+  })
+  ctx.effect?.(() => () => { viewer.stop().catch(() => {}) })
+
   try {
     if (typeof ctx.tools.get === 'function' && ctx.tools.get('pdf-open')) return
   } catch { /* 老版本没有 get()，交给 register 的重名错误兜底 */ }
@@ -59,14 +103,18 @@ export function apply(ctx, config = {}) {
         '在侧栏用 DSH 原生的 PDF 预览打开本地 PDF——客户端直接渲染，不生成图片、不起本地服务、有文字层；'
         + '只在明确要原生预览时用；默认入口是 pdf-view（按页码跳页、整本浏览）。'
         + '打开 PDF 文件先过这个工具（或 pdf-view），不要自己拼 sidebar_open 路径——这里还要解析文件名片段和会话工作目录。'
-        + 'file 给 PDF 路径或文件名片段（相对路径按会话工作目录解析）。返回文件路径，交给 sidebar_open 打开。',
+        + 'file 给 PDF 路径或文件名片段（相对路径按会话工作目录解析）。'
+        + '这个工具会自己调 sidebar_open 打开原生预览；本会话没有 sidebar_open 时，回落到 pdf-view 的渲染查看器并返回可点的 url（opened=false）。',
       parameters,
       output,
       isConcurrencySafe: () => true,
       async execute(args, exec) {
-        const cwd = args.cwd ? resolve(String(args.cwd)) : sessionCwd(ctx, exec)
+        const cwd = args.cwd ? resolve(String(args.cwd)) : await sessionCwd(ctx, exec)
         const pdf = resolvePdf(args.file, cwd, extraRoots)
-        return { ok: true, file: pdf }
+        if (await openInSidebar(ctx, exec, pdf)) return { ok: true, file: pdf, opened: true }
+        const port = await viewer.start()
+        const id = registerFile(pdf)
+        return { ok: true, file: pdf, opened: false, url: `http://127.0.0.1:${port}/v/${id}/1` }
       },
     })
   } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pdf-jump",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "在 DSH 侧栏里看本地 PDF：跳到任意一页，整本连着看。",
   "type": "module",
   "main": "index.js",
@@ -21,7 +21,7 @@
   ],
   "engines": {
     "node": "^22.19.0 || >=24.0.0",
-    "dsh": ">=0.2.1-0 <0.3.0-0"
+    "dsh": ">=0.2.1-0"
   },
   "dependencies": {
     "@napi-rs/canvas": "1.0.13",