dsh-plugin-litsearch 0.2.0 → 0.3.5

package/lib/host/export/bibtex.js

@@ -1,5 +1,5 @@
 /** BibTeX 导出。 */
-import { groupName, paperNote } from './common.js';
+import { groupName } from './common.js';
 import { stateOf } from '../tasks/states.js';
 export function renderBibtex(context) {
     return `${context.papers
@@ -22,9 +22,6 @@ export function renderBibtex(context) {
         const group = groupName(context.task, state.groupId);
         if (group !== '')
             fields.push(['keywords', group]);
-        const note = paperNote(context.task, paper);
-        if (note !== '')
-            fields.push(['note', note]);
         const body = fields
             .map(([name, value]) => `  ${name} = {${escapeBibtex(value)}}`)
             .join(',\n');

package/lib/host/export/common.d.ts

@@ -11,8 +11,6 @@ export interface ExportContext {
 }
 export declare function queryName(task: SearchTask, queryId: string): string;
 export declare function groupName(task: SearchTask, groupId: string | undefined): string;
-export declare function paperNote(task: SearchTask, paper: Paper): string;
-export declare function paperTags(task: SearchTask, paper: Paper): string[];
 export declare function isoDate(date: Date): string;
 /** 文件名用的安全任务 id（导出统一按 id 命名，避免标题里的路径字符）。 */
 export declare function exportStem(task: SearchTask, date: Date): string;

package/lib/host/export/common.js

@@ -1,7 +1,6 @@
 /**
  * 导出共用上下文：把任务、待导出论文与可选的对比基准打包给各格式渲染器。
  */
-import { stateOf } from '../tasks/states.js';
 export function queryName(task, queryId) {
     return task.conditions.queries.find((query) => query.id === queryId)?.name ?? queryId;
 }
@@ -10,12 +9,6 @@ export function groupName(task, groupId) {
         return '';
     return task.groups.find((group) => group.id === groupId)?.name ?? '';
 }
-export function paperNote(task, paper) {
-    return stateOf(task, paper.paperId).note ?? '';
-}
-export function paperTags(task, paper) {
-    return stateOf(task, paper.paperId).tags ?? [];
-}
 export function isoDate(date) {
     return date.toISOString().slice(0, 10);
 }

package/lib/host/export/csv.js

@@ -4,7 +4,7 @@
  * 列顺序与第一版方案一致，后续全文能力只需填 `pdfStatus` / `pdfError`，不改列。
  * 带 UTF-8 BOM，方便 Excel 直接打开中文。
  */
-import { groupName, paperNote, queryName } from './common.js';
+import { groupName, queryName } from './common.js';
 import { pdfStatusOf } from '../tasks/filter.js';
 import { stateOf } from '../tasks/states.js';
 const COLUMNS = [
@@ -24,10 +24,8 @@ const COLUMNS = [
     'language',
     'screening',
     'group',
-    'shortlistOrder',
     'pdfStatus',
     'pdfError',
-    'note',
 ];
 export function renderCsv(context) {
     const { task, papers } = context;
@@ -51,10 +49,8 @@ export function renderCsv(context) {
             paper.language ?? '',
             state.screening,
             groupName(task, state.groupId),
-            state.shortlistOrder === undefined ? '' : String(state.shortlistOrder),
             pdfStatusOf(task, paper),
             state.pdfError ?? '',
-            paperNote(task, paper),
         ]
             .map(csvCell)
             .join(','));

package/lib/host/export/markdown.d.ts

@@ -1,5 +1,5 @@
 /**
- * Markdown 检索报告：检索式组（可复现）、规模漏斗、分组阅读清单、必读路线、
+ * Markdown 检索报告：检索式组（可复现）、规模漏斗、分组阅读清单、
  * 对比差异与研究笔记。结构对齐两份真实产出。
  */
 import type { ExportContext } from './common.js';

package/lib/host/export/markdown.js

@@ -1,12 +1,11 @@
 /**
- * Markdown 检索报告：检索式组（可复现）、规模漏斗、分组阅读清单、必读路线、
+ * Markdown 检索报告：检索式组（可复现）、规模漏斗、分组阅读清单、
  * 对比差异与研究笔记。结构对齐两份真实产出。
  */
 import { compareTasks } from '../tasks/compare.js';
-import { sortGroupPapers, stateOf } from '../tasks/states.js';
+import { stateOf } from '../tasks/states.js';
 import { isoDate } from './common.js';
 const TOP_COMPARE = 30;
-const TOP_ROUTE = 30;
 export function renderMarkdown(context) {
     const { task, papers, base, generatedAt } = context;
     const lines = [];
@@ -43,10 +42,10 @@ export function renderMarkdown(context) {
             lines.push('_（暂无文献）_', '');
         }
         else {
-            lines.push('| # | 文献 | 年份 / 出处 | 为什么读 | 状态 |');
-            lines.push('|---:|---|---|---|---|');
-            sortGroupPapers(task, items).forEach((paper, index) => {
-                lines.push(`| ${index + 1} | ${paperLabel(paper)} | ${metaLabel(paper)} | ${cell(stateOf(task, paper.paperId).note ?? '')} | ${stateOf(task, paper.paperId).screening} |`);
+            lines.push('| # | 文献 | 年份 / 出处 | 状态 |');
+            lines.push('|---:|---|---|---|');
+            items.forEach((paper, index) => {
+                lines.push(`| ${index + 1} | ${paperLabel(paper)} | ${metaLabel(paper)} | ${stateOf(task, paper.paperId).screening} |`);
             });
             lines.push('');
         }
@@ -54,31 +53,15 @@ export function renderMarkdown(context) {
     const ungrouped = papers.filter((paper) => stateOf(task, paper.paperId).groupId === undefined);
     if (ungrouped.length > 0) {
         lines.push(`### 未分组（${ungrouped.length} 篇）`, '');
-        lines.push('| # | 文献 | 年份 / 出处 | 为什么读 | 状态 |');
-        lines.push('|---:|---|---|---|---|');
+        lines.push('| # | 文献 | 年份 / 出处 | 状态 |');
+        lines.push('|---:|---|---|---|');
         ungrouped.slice(0, 120).forEach((paper, index) => {
-            lines.push(`| ${index + 1} | ${paperLabel(paper)} | ${metaLabel(paper)} | ${cell(stateOf(task, paper.paperId).note ?? '')} | ${stateOf(task, paper.paperId).screening} |`);
+            lines.push(`| ${index + 1} | ${paperLabel(paper)} | ${metaLabel(paper)} | ${stateOf(task, paper.paperId).screening} |`);
         });
         if (ungrouped.length > 120)
             lines.push('', `_（仅列出前 120 篇，完整清单见 CSV）_`);
         lines.push('');
     }
-    const route = papers
-        .filter((paper) => stateOf(task, paper.paperId).shortlistOrder !== undefined)
-        .sort((a, b) => (stateOf(task, a.paperId).shortlistOrder ?? 0) -
-        (stateOf(task, b.paperId).shortlistOrder ?? 0))
-        .slice(0, TOP_ROUTE);
-    lines.push('## 必读阅读路线', '');
-    if (route.length === 0) {
-        lines.push('_（尚未标记必读顺序）_', '');
-    }
-    else {
-        route.forEach((paper, index) => {
-            const note = stateOf(task, paper.paperId).note;
-            lines.push(`${index + 1}. ${paperLabel(paper)}${note === undefined ? '' : ` — ${note}`}`);
-        });
-        lines.push('');
-    }
     lines.push('## 全文获取情况', '');
     const oa = papers.filter((paper) => paper.openAccess).length;
     const pdf = papers.filter((paper) => paper.pdfUrl !== '').length;

package/lib/host/export/ris.js

@@ -1,5 +1,5 @@
 /** RIS 导出（供 Zotero / EndNote 导入）。 */
-import { groupName, paperNote, paperTags } from './common.js';
+import { groupName } from './common.js';
 import { stateOf } from '../tasks/states.js';
 export function renderRis(context) {
     const blocks = context.papers.map((paper) => {
@@ -18,9 +18,6 @@ export function renderRis(context) {
         const group = groupName(context.task, state.groupId);
         if (group !== '')
             push(lines, 'KW', group);
-        for (const tag of paperTags(context.task, paper))
-            push(lines, 'KW', tag);
-        push(lines, 'N1', paperNote(context.task, paper));
         if (state.screening !== 'unread')
             push(lines, 'N1', `screening: ${state.screening}`);
         lines.push('ER  - ');

package/lib/host/paths.d.ts

@@ -7,10 +7,11 @@
  *
  * - 只复制、不删除，旧目录原样保留作备份；
  * - 不覆盖新目录里已有的文件，重复启动不会反复迁移；
- * - 复制失败或校验不通过时回退到旧目录读取，保证任务标注不丢。
+ * - 复制失败或校验不通过时回退到旧目录读取，保证任务数据不丢。
  *
- * PDF 的可读文件由设置项 `pdfRoot` 决定（默认 `~/Downloads/dsh-litsearch`），
- * 不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs` 随数据目录一起搬迁。
+ * PDF 的可读文件由设置项 `pdfRoot` 决定（默认落在当前会话工作目录下的
+ * `dsh-litsearch/`），不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs`
+ * 随数据目录一起搬迁。
  */
 export declare const PLUGIN_ID = "dsh-plugin-litsearch";
 /** 历史版本使用的目录名（`$DSH_HOME` 下的一级目录）。 */

package/lib/host/paths.js

@@ -7,10 +7,11 @@
  *
  * - 只复制、不删除，旧目录原样保留作备份；
  * - 不覆盖新目录里已有的文件，重复启动不会反复迁移；
- * - 复制失败或校验不通过时回退到旧目录读取，保证任务标注不丢。
+ * - 复制失败或校验不通过时回退到旧目录读取，保证任务数据不丢。
  *
- * PDF 的可读文件由设置项 `pdfRoot` 决定（默认 `~/Downloads/dsh-litsearch`），
- * 不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs` 随数据目录一起搬迁。
+ * PDF 的可读文件由设置项 `pdfRoot` 决定（默认落在当前会话工作目录下的
+ * `dsh-litsearch/`），不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs`
+ * 随数据目录一起搬迁。
  */
 import { copyFile, mkdir, readdir, rm, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';

package/lib/host/pdf/root.d.ts

@@ -0,0 +1,11 @@
+/**
+ * PDF 下载目录的纯路径计算。
+ *
+ * 优先级：显式配置 `pdfRoot` → 会话工作目录下的 `dsh-litsearch/` →
+ * 历史默认 `~/Downloads/dsh-litsearch`。保持无相对导入，便于单测直接加载。
+ */
+/** 工作目录（或 Downloads）下的固定子目录名。 */
+export declare const PDF_SUBDIR = "dsh-litsearch";
+/** 展开 `~` / `~/...`；其它路径原样返回。 */
+export declare function expandHomePath(path: string, home?: string): string;
+export declare function resolvePdfRootPath(configured: string, workspace: string | undefined, home?: string): string;

package/lib/host/pdf/root.js

@@ -0,0 +1,27 @@
+/**
+ * PDF 下载目录的纯路径计算。
+ *
+ * 优先级：显式配置 `pdfRoot` → 会话工作目录下的 `dsh-litsearch/` →
+ * 历史默认 `~/Downloads/dsh-litsearch`。保持无相对导入，便于单测直接加载。
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** 工作目录（或 Downloads）下的固定子目录名。 */
+export const PDF_SUBDIR = 'dsh-litsearch';
+/** 展开 `~` / `~/...`；其它路径原样返回。 */
+export function expandHomePath(path, home = homedir()) {
+    if (path === '~')
+        return home;
+    if (path.startsWith('~/'))
+        return join(home, path.slice(2));
+    return path;
+}
+export function resolvePdfRootPath(configured, workspace, home = homedir()) {
+    const custom = configured.trim();
+    if (custom !== '')
+        return expandHomePath(custom, home);
+    const base = workspace?.trim() ?? '';
+    if (base !== '')
+        return join(base, PDF_SUBDIR);
+    return join(home, 'Downloads', PDF_SUBDIR);
+}

package/lib/host/pdf/store.d.ts

@@ -4,7 +4,7 @@
  * 安全约束：只允许 http/https、拒绝回环/私网/链路本地地址、最多 5 次重定向、
  * 20 秒超时、体积上限可配；只有以 `%PDF-` 开头的内容才会被当成 PDF。
  */
-import type { Paper, PdfStatus } from '../../search/types.js';
+import type { Paper, PdfFailureReason, PdfStatus } from '../../search/types.js';
 export type PdfFailure = 'paywalled' | 'blocked' | 'failed' | 'not_pdf' | 'too_large' | 'unsafe';
 export declare class PdfFetchError extends Error {
     readonly kind: PdfFailure;
@@ -17,9 +17,13 @@ export interface PdfResolution {
     buffer?: Buffer;
     url?: string;
     error?: string;
+    /** 失败根因；成功时缺省。 */
+    reason?: PdfFailureReason;
 }
-/** 设置里的根目录；空串回落到 ~/Downloads/dsh-litsearch。 */
-export declare function resolvePdfRoot(): string;
+/** 把技术错误整理成「发生了什么 + 下一步做什么」，供界面直接展示。 */
+export declare function pdfFailureMessage(reason: PdfFailureReason, detail: string, attempted: number): string;
+/** 设置里的根目录；未配置时落在会话工作目录下的 dsh-litsearch/。 */
+export declare function resolvePdfRoot(workspace?: string): string;
 export declare function pdfCacheDir(storageRoot: string): string;
 /** 尝试所有候选并返回第一个合法 PDF；失败时给出可展示的状态与原因。 */
 export declare function resolvePdf(paper: Paper, signal?: AbortSignal): Promise<PdfResolution>;
@@ -31,7 +35,7 @@ export interface FetchPdfOptions {
 /** 下载并校验单个 PDF；内部处理重定向，每一步都重新校验目标地址。 */
 export declare function fetchPdf(url: string, options?: FetchPdfOptions): Promise<Buffer>;
 /** 写入去重缓存与用户目录；返回两份路径。 */
-export declare function persistPdf(buffer: Buffer, storageRoot: string, paper: Paper): Promise<{
+export declare function persistPdf(buffer: Buffer, storageRoot: string, paper: Paper, workspace?: string): Promise<{
     cachePath: string;
     filePath: string;
     filename: string;
@@ -40,15 +44,21 @@ export declare function persistPdf(buffer: Buffer, storageRoot: string, paper: P
 export declare function readSavedPdf(filePath: string): Promise<Buffer | null>;
 /** `<第一作者><年份>_<短标题>_<PMID|DOI>.pdf`，去掉路径分隔符。 */
 export declare function readableFilename(paper: Paper): string;
-/** 预览时读取已保存的可读文件；没有则返回 null（由调用方决定是否联网）。 */
-export declare function readLocalPdf(paper: Paper): Promise<Buffer | null>;
 /** 清理 PDF 缓存目录。 */
 export declare function cleanupPdfCache(storageRoot: string): Promise<{
     removed: number;
     freedBytes: number;
 }>;
+/**
+ * 按总量上限修剪去重缓存：超出时从最旧（mtime）开始删，直到不超过上限。
+ * `maxBytes <= 0` 表示关闭自动清理。
+ */
+export declare function prunePdfCache(storageRoot: string, maxBytes: number): Promise<{
+    removed: number;
+    freedBytes: number;
+}>;
 /** 测试下载目录是否可写（设置页）。 */
-export declare function probePdfRoot(): Promise<{
+export declare function probePdfRoot(workspace?: string): Promise<{
     root: string;
     writable: boolean;
     error?: string;

package/lib/host/pdf/store.js

@@ -7,11 +7,11 @@
 import { createHash } from 'node:crypto';
 import { lookup } from 'node:dns/promises';
 import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { isIP } from 'node:net';
 import { join } from 'node:path';
 import { getSettings } from '../../search/config.js';
-import { epmcXmlUrl, pdfCandidates, unpaywallPdfCandidates } from '../../search/oa.js';
+import { epmcXmlUrl, isPdfRenderUrl, pdfCandidates, unpaywallPdfCandidates, } from '../../search/oa.js';
+import { resolvePdfRootPath } from './root.js';
 const MAX_REDIRECTS = 5;
 const FETCH_TIMEOUT_MS = 20_000;
 const MAX_PDF_BYTES_DEFAULT = 30 * 1024 * 1024;
@@ -26,16 +26,22 @@ export class PdfFetchError extends Error {
             this.status = status;
     }
 }
-/** 设置里的根目录；空串回落到 ~/Downloads/dsh-litsearch。 */
-export function resolvePdfRoot() {
-    const configured = getSettings().pdfRoot.trim();
-    if (configured === '')
-        return join(homedir(), 'Downloads', 'dsh-litsearch');
-    if (configured === '~')
-        return homedir();
-    if (configured.startsWith('~/'))
-        return join(homedir(), configured.slice(2));
-    return configured;
+/** 分类对应的下一步指引：后台拿不到时明确告诉用户去浏览器手动保存。 */
+const FAILURE_HINTS = {
+    'no-candidate': '请在浏览器打开原文或 PDF 链接手动保存（订阅文献无法自动下载）',
+    blocked: '请在浏览器打开 PDF 链接手动保存（后台请求可能被要求登录、订阅或人机验证）',
+    paywalled: '该文献需要订阅，请在浏览器登录后手动保存',
+    'not-pdf': '请在浏览器打开 PDF 链接手动保存',
+    failed: '可稍后重试，若持续失败请在浏览器打开原文手动保存',
+};
+/** 把技术错误整理成「发生了什么 + 下一步做什么」，供界面直接展示。 */
+export function pdfFailureMessage(reason, detail, attempted) {
+    const suffix = attempted > 1 ? `（已尝试 ${attempted} 个候选）` : '';
+    return `${detail}${suffix}；${FAILURE_HINTS[reason]}`;
+}
+/** 设置里的根目录；未配置时落在会话工作目录下的 dsh-litsearch/。 */
+export function resolvePdfRoot(workspace) {
+    return resolvePdfRootPath(getSettings().pdfRoot, workspace);
 }
 export function pdfCacheDir(storageRoot) {
     return join(storageRoot, 'pdfs');
@@ -44,15 +50,21 @@ export function pdfCacheDir(storageRoot) {
 export async function resolvePdf(paper, signal) {
     const settings = getSettings();
     const maxBytes = settings.pdfMaxMb * 1024 * 1024;
-    const candidates = pdfCandidates(paper);
+    const fromMetadata = pdfCandidates(paper);
     const extra = await unpaywallPdfCandidates(paper.doi, settings.contactEmail, Math.min(settings.requestTimeoutMs, 8_000), signal);
-    for (const url of extra)
-        if (!candidates.includes(url))
-            candidates.push(url);
+    // 静态直链优先、Unpaywall 补出的 OA 直链次之，渲染页放最后兜底：
+    // Europe PMC / PMC 的渲染页对后台请求几乎必然返回 403 或 HTML，
+    // 让它们排在优质候选前面只会拖慢下载并掩盖真正的失败原因。
+    const candidates = [
+        ...fromMetadata.filter((url) => !isPdfRenderUrl(url)),
+        ...extra,
+        ...fromMetadata.filter(isPdfRenderUrl),
+    ];
+    const unique = [...new Set(candidates)];
     let last = null;
     let sawBlocked = false;
     let sawPaywalled = false;
-    for (const url of candidates) {
+    for (const url of unique) {
         try {
             const buffer = await fetchPdf(url, { maxBytes, signal });
             return { ok: true, status: 'available', buffer, url };
@@ -71,10 +83,17 @@ export async function resolvePdf(paper, signal) {
         }
     }
     const status = sawBlocked ? 'blocked' : sawPaywalled ? 'paywalled' : 'failed';
-    const error = last === null
-        ? '没有可尝试的 PDF 地址'
-        : `${last.message}${candidates.length > 1 ? `（已尝试 ${candidates.length} 个候选）` : ''}`;
-    return { ok: false, status, error };
+    const reason = last === null
+        ? 'no-candidate'
+        : sawBlocked
+            ? 'blocked'
+            : sawPaywalled
+                ? 'paywalled'
+                : last.kind === 'not_pdf'
+                    ? 'not-pdf'
+                    : 'failed';
+    const detail = last === null ? '未找到可后台下载的开放获取 PDF' : last.message;
+    return { ok: false, status, reason, error: pdfFailureMessage(reason, detail, unique.length) };
 }
 /** 下载并校验单个 PDF；内部处理重定向，每一步都重新校验目标地址。 */
 export async function fetchPdf(url, options = {}) {
@@ -92,7 +111,11 @@ export async function fetchPdf(url, options = {}) {
             const response = await fetch(current, {
                 redirect: 'manual',
                 signal: controller.signal,
-                headers: { accept: 'application/pdf,application/octet-stream;q=0.9,*/*;q=0.5' },
+                headers: {
+                    accept: 'application/pdf,application/octet-stream;q=0.9,*/*;q=0.5',
+                    'accept-language': 'zh-CN,zh;q=0.9,en;q=0.8',
+                    'user-agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36',
+                },
             });
             if (response.status >= 300 && response.status < 400) {
                 const location = response.headers.get('location');
@@ -104,8 +127,11 @@ export async function fetchPdf(url, options = {}) {
             if (response.status === 401 || response.status === 402) {
                 throw new PdfFetchError('paywalled', `需要订阅或登录（HTTP ${response.status}）`, response.status);
             }
-            if (response.status === 403 || response.status === 429) {
-                throw new PdfFetchError('blocked', `出版商拒绝访问（HTTP ${response.status}）`, response.status);
+            if (response.status === 429) {
+                throw new PdfFetchError('blocked', '请求过于频繁（HTTP 429），请稍后重试', response.status);
+            }
+            if (response.status === 403) {
+                throw new PdfFetchError('blocked', '出版商拒绝访问（HTTP 403）', response.status);
             }
             if (!response.ok) {
                 throw new PdfFetchError('failed', `下载失败（HTTP ${response.status}）`, response.status);
@@ -116,6 +142,10 @@ export async function fetchPdf(url, options = {}) {
             }
             const buffer = await readCapped(response, maxBytes);
             if (buffer.length < 5 || buffer.subarray(0, 5).toString('latin1') !== '%PDF-') {
+                const head = buffer.subarray(0, 2048).toString('latin1');
+                if (/Just a moment|cf-mitigated|Enable JavaScript and cookies/i.test(head)) {
+                    throw new PdfFetchError('blocked', '出版商启用了人机验证，后台无法直接下载');
+                }
                 throw new PdfFetchError('not_pdf', '返回内容不是 PDF（可能是 HTML 登录/摘要页）');
             }
             return buffer;
@@ -138,13 +168,13 @@ export async function fetchPdf(url, options = {}) {
     throw new PdfFetchError('failed', `重定向超过 ${MAX_REDIRECTS} 次`);
 }
 /** 写入去重缓存与用户目录；返回两份路径。 */
-export async function persistPdf(buffer, storageRoot, paper) {
+export async function persistPdf(buffer, storageRoot, paper, workspace) {
     const hash = createHash('sha256').update(buffer).digest('hex');
     const cacheDir = pdfCacheDir(storageRoot);
     await mkdir(cacheDir, { recursive: true });
     const cachePath = join(cacheDir, `${hash}.pdf`);
     await writeFile(cachePath, buffer);
-    const root = resolvePdfRoot();
+    const root = resolvePdfRoot(workspace);
     await mkdir(root, { recursive: true });
     const filename = readableFilename(paper);
     const filePath = join(root, filename);
@@ -177,10 +207,6 @@ export function readableFilename(paper) {
     const base = `${author}${year}_${title === '' ? 'untitled' : title}_${safeId}`;
     return `${base.slice(0, 120)}.pdf`;
 }
-/** 预览时读取已保存的可读文件；没有则返回 null（由调用方决定是否联网）。 */
-export async function readLocalPdf(paper) {
-    return readSavedPdf(join(resolvePdfRoot(), readableFilename(paper)));
-}
 /** 清理 PDF 缓存目录。 */
 export async function cleanupPdfCache(storageRoot) {
     const dir = pdfCacheDir(storageRoot);
@@ -206,9 +232,61 @@ export async function cleanupPdfCache(storageRoot) {
     }
     return { removed, freedBytes };
 }
+/**
+ * 按总量上限修剪去重缓存：超出时从最旧（mtime）开始删，直到不超过上限。
+ * `maxBytes <= 0` 表示关闭自动清理。
+ */
+export async function prunePdfCache(storageRoot, maxBytes) {
+    if (!Number.isFinite(maxBytes) || maxBytes <= 0)
+        return { removed: 0, freedBytes: 0 };
+    const dir = pdfCacheDir(storageRoot);
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return { removed: 0, freedBytes: 0 };
+    }
+    const files = [];
+    let total = 0;
+    for (const name of names) {
+        if (!name.endsWith('.pdf'))
+            continue;
+        const path = join(dir, name);
+        try {
+            const info = await stat(path);
+            if (!info.isFile())
+                continue;
+            files.push({ path, size: info.size, mtimeMs: info.mtimeMs });
+            total += info.size;
+        }
+        catch {
+            // 单个缓存文件读不到元信息时跳过，不影响修剪其余文件。
+        }
+    }
+    if (total <= maxBytes)
+        return { removed: 0, freedBytes: 0 };
+    files.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    let removed = 0;
+    let freedBytes = 0;
+    for (const file of files) {
+        if (total <= maxBytes)
+            break;
+        try {
+            await rm(file.path, { force: true });
+            total -= file.size;
+            freedBytes += file.size;
+            removed += 1;
+        }
+        catch {
+            // 删除失败继续尝试更近的文件。
+        }
+    }
+    return { removed, freedBytes };
+}
 /** 测试下载目录是否可写（设置页）。 */
-export async function probePdfRoot() {
-    const root = resolvePdfRoot();
+export async function probePdfRoot(workspace) {
+    const root = resolvePdfRoot(workspace);
     const probe = join(root, `.write-test-${process.pid}-${Date.now()}`);
     try {
         await mkdir(root, { recursive: true });