dsh-plugin-litsearch 0.3.0 → 0.3.5

package/lib/host/tasks/service.js

@@ -5,7 +5,7 @@
  * 模型工具与面板 HTTP 路由都只调用这里，保证两边操作同一份状态。
  */
 import { randomUUID } from 'node:crypto';
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdir, rm, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { MAX_LIMIT, PLUGIN_VERSION, getSettings } from '../../search/config.js';
 import { SearchError } from '../../search/errors.js';
@@ -17,7 +17,7 @@ import { fetchPubtatorEntities } from '../../search/pubtator-entities.js';
 import { SOURCE_IDS } from '../../search/types.js';
 import { TaskEvents } from '../events.js';
 import { buildExport } from '../export/index.js';
-import { cleanupPdfCache, epmcFullTextAvailable, persistPdf, probePdfRoot, prunePdfCache, readLocalPdf, readSavedPdf, readableFilename, resolvePdf, resolvePdfRoot, } from '../pdf/store.js';
+import { cleanupPdfCache, epmcFullTextAvailable, persistPdf, probePdfRoot, prunePdfCache, readSavedPdf, readableFilename, resolvePdf, resolvePdfRoot, } from '../pdf/store.js';
 import { ZoteroConnector } from '../zotero/connector.js';
 import { normalizeWorkspace } from '../workspace.js';
 import { compareTasks } from './compare.js';
@@ -32,6 +32,48 @@ const MAX_TITLE = 120;
 const MAX_PAGE_LIMIT = 200;
 const MAX_TYPES = 20;
 const PROBE_QUERY = 'machine learning';
+/** 已下载文件存在性检查的短缓存：详情轮询时不必反复 stat 同一批文件。 */
+const PDF_EXISTS_TTL_MS = 10_000;
+const pdfExistsCache = new Map();
+async function pdfFileExists(filePath) {
+    const cached = pdfExistsCache.get(filePath);
+    if (cached !== undefined && Date.now() - cached.at < PDF_EXISTS_TTL_MS)
+        return cached.exists;
+    const exists = await stat(filePath)
+        .then((info) => info.isFile())
+        .catch(() => false);
+    pdfExistsCache.set(filePath, { exists, at: Date.now() });
+    return exists;
+}
+/**
+ * 已下载的 PDF 可能被用户在文件管理器里删掉（也可能从废纸篓恢复）：
+ * 每次读取任务时校准状态，删除后回到 `missing`，点击即可重新下载。
+ */
+async function reconcilePdfFiles(task) {
+    const downloads = Object.entries(task.states).filter(([, state]) => state.pdfFile !== undefined &&
+        (state.pdfStatus === 'downloaded' || state.pdfStatus === 'missing'));
+    if (downloads.length === 0)
+        return false;
+    const checks = await Promise.all(downloads.map(async ([paperId, state]) => ({
+        paperId,
+        exists: await pdfFileExists(state.pdfFile ?? ''),
+    })));
+    let changed = false;
+    for (const { paperId, exists } of checks) {
+        const current = task.states[paperId];
+        if (current === undefined)
+            continue;
+        if (current.pdfStatus === 'downloaded' && !exists) {
+            task.states[paperId] = { ...current, pdfStatus: 'missing' };
+            changed = true;
+        }
+        else if (current.pdfStatus === 'missing' && exists) {
+            task.states[paperId] = { ...current, pdfStatus: 'downloaded' };
+            changed = true;
+        }
+    }
+    return changed;
+}
 export class TaskService {
     ready;
     store = new TaskStore();
@@ -183,8 +225,12 @@ export class TaskService {
             task.rounds = [];
         return task;
     }
-    async getDetail(id) {
-        return toDetail(await this.get(id));
+    async getDetail(id, workspace) {
+        const task = await this.get(id);
+        if (await reconcilePdfFiles(task))
+            await this.store.save(task);
+        const target = normalizeWorkspace(workspace) ?? normalizeWorkspace(task.workspace);
+        return { ...toDetail(task), downloadDir: resolvePdfRoot(target) };
     }
     /** 任务内轮次历史（时间升序、深拷贝）。 */
     async getRounds(id) {
@@ -445,7 +491,7 @@ export class TaskService {
         const resolved = base === undefined ? filter : await this.withBaseFilter(task, filter);
         return computeStats(task, resolved, scope, base);
     }
-    /** 写入筛读 / 分组 / 必读 / 备注；返回新的 rev 与命中条数。 */
+    /** 写入筛读 / 分组；返回新的 rev 与命中条数。 */
     async annotate(id, inputs, expectedRev) {
         const task = await this.get(id);
         if (expectedRev !== undefined && expectedRev !== task.rev) {
@@ -519,6 +565,27 @@ export class TaskService {
             remaining: this.store.list().length,
         };
     }
+    /**
+     * 「查看已下载」前的存在性检查：页面加载后文件可能被删除或移走。
+     * 缺失时把状态改为 `missing` 并广播，所有面板随即显示「下载文件已删除」。
+     */
+    async recheckPdf(id, paperId) {
+        const task = await this.get(id);
+        findPaper(task, paperId);
+        const state = task.states[paperId];
+        const filePath = state?.pdfFile;
+        if (state === undefined || filePath === undefined)
+            return { exists: false };
+        pdfExistsCache.delete(filePath);
+        const exists = await pdfFileExists(filePath);
+        if (exists && state.pdfStatus !== 'downloaded') {
+            await this.setPdfState(task, paperId, { pdfStatus: 'downloaded', pdfFile: filePath });
+        }
+        else if (!exists && state.pdfStatus !== 'missing') {
+            await this.setPdfState(task, paperId, { pdfStatus: 'missing', pdfFile: filePath });
+        }
+        return { exists };
+    }
     /** 下载单篇 PDF；失败时写入失败状态，若有 EPMC 全文则降级为 html-only。 */
     async downloadPdf(id, paperId, workspace) {
         const task = await this.get(id);
@@ -539,6 +606,7 @@ export class TaskService {
                 status: fallback,
                 bytes: 0,
                 error: resolution.error ?? '下载失败',
+                ...(resolution.reason === undefined ? {} : { reason: resolution.reason }),
             };
             return result;
         }
@@ -558,23 +626,6 @@ export class TaskService {
             result.url = resolution.url;
         return result;
     }
-    /** PDF 预览：优先用已落地文件；没有则临时抓取一次但不落盘。 */
-    async previewPdf(id, paperId, workspace) {
-        const task = await this.get(id);
-        const paper = findPaper(task, paperId);
-        const filename = readableFilename(paper);
-        const target = normalizeWorkspace(workspace) ?? normalizeWorkspace(task.workspace);
-        const recorded = task.states[paperId]?.pdfFile;
-        const saved = recorded === undefined ? null : await readSavedPdf(recorded);
-        const local = saved ?? (await readLocalPdf(paper, target));
-        if (local !== null)
-            return { buffer: local, filename };
-        const resolution = await resolvePdf(paper);
-        if (!resolution.ok || resolution.buffer === undefined) {
-            throw new SearchError('not_found', resolution.error ?? '没有可预览的 PDF');
-        }
-        return { buffer: resolution.buffer, filename };
-    }
     /** Europe PMC 全文（JATS → 只含安全标签的 HTML）。 */
     async fullText(id, paperId) {
         const task = await this.get(id);
@@ -596,15 +647,19 @@ export class TaskService {
         return html;
     }
     /** 单篇论文详情：独立论文页使用，含任务标题与分组。 */
-    async paperDetail(id, paperId) {
+    async paperDetail(id, paperId, workspace) {
         const task = await this.get(id);
+        if (await reconcilePdfFiles(task))
+            await this.store.save(task);
         const paper = findPaper(task, paperId);
+        const target = normalizeWorkspace(workspace) ?? normalizeWorkspace(task.workspace);
         const detail = {
             taskId: task.id,
             taskTitle: task.title,
             rev: task.rev,
             paper,
             groups: task.groups,
+            downloadDir: resolvePdfRoot(target),
         };
         const state = task.states[paperId];
         if (state !== undefined)
@@ -656,7 +711,9 @@ export class TaskService {
         const inputs = [];
         for (const paper of wanted) {
             const state = task.states[paper.paperId];
-            const tags = state?.tags ?? [];
+            // 标签已移除，用任务内的分组名承载 Zotero 侧的分类信息。
+            const group = task.groups.find((entry) => entry.id === state?.groupId);
+            const tags = group === undefined ? [] : [group.name];
             const pdfPath = attachPdf
                 ? await this.ensureLocalPdf(paper, target, state?.pdfFile)
                 : undefined;
@@ -721,6 +778,10 @@ export class TaskService {
             delete next.pdfFile;
         else
             next.pdfFile = patch.pdfFile.slice(0, 1024);
+        // 刚写入的文件立即视为存在，避免存在性缓存把状态又翻回 `missing`。
+        if (patch.pdfStatus === 'downloaded' && next.pdfFile !== undefined) {
+            pdfExistsCache.set(next.pdfFile, { exists: true, at: Date.now() });
+        }
         task.states[paperId] = next;
         task.rev += 1;
         task.updatedAt = new Date().toISOString();
@@ -970,14 +1031,8 @@ function readTitle(title, conditions) {
 function inheritStates(base) {
     const states = {};
     for (const [paperId, state] of Object.entries(base.states)) {
-        // 分组是任务内概念，继承时只带筛读、必读顺序、备注与标签。
+        // 分组是任务内概念，继承时只带筛读状态。
         const next = { screening: state.screening };
-        if (state.shortlistOrder !== undefined)
-            next.shortlistOrder = state.shortlistOrder;
-        if (state.note !== undefined)
-            next.note = state.note;
-        if (state.tags !== undefined)
-            next.tags = [...state.tags];
         states[paperId] = next;
     }
     return states;

package/lib/host/tasks/states.d.ts

@@ -1,5 +1,5 @@
 /**
- * 筛读台账：论文级状态（四态筛读 / 分组 / 必读顺序 / 备注 / 标签）与任务分组。
+ * 筛读台账：论文级状态（四态筛读 / 分组）与任务分组。
  *
  * 所有写入口（面板注解、模型 `literature_task annotate`、分组编辑）都先经过
  * 这里的校验，确保状态结构稳定；`states` 以稳定的 `paperId` 为键，因此跨任务
@@ -24,5 +24,3 @@ export declare function applyAnnotations(task: SearchTask, inputs: readonly Anno
 export declare function normalizeGroups(values: readonly TaskGroup[] | undefined): TaskGroup[] | undefined;
 /** 分组若仍有论文引用，删除前提醒调用方（调用方决定是否允许）。 */
 export declare function groupUsage(task: SearchTask, groupId: string): number;
-/** 按必读顺序、年份、标题排序某组的论文。 */
-export declare function sortGroupPapers(task: SearchTask, papers: readonly Paper[]): Paper[];

package/lib/host/tasks/states.js

@@ -1,5 +1,5 @@
 /**
- * 筛读台账：论文级状态（四态筛读 / 分组 / 必读顺序 / 备注 / 标签）与任务分组。
+ * 筛读台账：论文级状态（四态筛读 / 分组）与任务分组。
  *
  * 所有写入口（面板注解、模型 `literature_task annotate`、分组编辑）都先经过
  * 这里的校验，确保状态结构稳定；`states` 以稳定的 `paperId` 为键，因此跨任务
@@ -10,17 +10,14 @@ const MAX_ANNOTATIONS = 50;
 const MAX_GROUPS = 50;
 const MAX_GROUP_NAME = 60;
 const MAX_GROUP_DESCRIPTION = 500;
-const MAX_NOTE = 4000;
-const MAX_TAGS = 20;
-const MAX_TAG = 40;
 const MAX_PDF_ERROR = 300;
 const MAX_PDF_FILE = 1024;
-const MAX_SHORTLIST_ORDER = 100_000;
 export const SCREENINGS = ['unread', 'read', 'included', 'excluded'];
 export const PDF_STATUSES = [
     'unknown',
     'available',
     'downloaded',
+    'missing',
     'html-only',
     'paywalled',
     'blocked',
@@ -86,40 +83,6 @@ export function applyAnnotations(task, inputs) {
             }
             touched = true;
         }
-        if (input.shortlistOrder !== undefined) {
-            if (input.shortlistOrder === null) {
-                delete next.shortlistOrder;
-            }
-            else {
-                if (!Number.isInteger(input.shortlistOrder) ||
-                    input.shortlistOrder < 0 ||
-                    input.shortlistOrder > MAX_SHORTLIST_ORDER) {
-                    throw new SearchError('bad_request', `shortlistOrder 必须是 0..${MAX_SHORTLIST_ORDER} 的整数`);
-                }
-                next.shortlistOrder = input.shortlistOrder;
-            }
-            touched = true;
-        }
-        if (input.note !== undefined) {
-            if (typeof input.note !== 'string')
-                throw new SearchError('bad_request', 'note 必须是字符串');
-            const note = input.note.trim();
-            if (note === '')
-                delete next.note;
-            else
-                next.note = note.slice(0, MAX_NOTE);
-            touched = true;
-        }
-        if (input.tags !== undefined) {
-            if (!Array.isArray(input.tags))
-                throw new SearchError('bad_request', 'tags 必须是字符串数组');
-            const tags = normalizeTags(input.tags);
-            if (tags.length === 0)
-                delete next.tags;
-            else
-                next.tags = tags;
-            touched = true;
-        }
         if (input.pdfStatus !== undefined) {
             if (!isPdfStatus(input.pdfStatus)) {
                 throw new SearchError('bad_request', `pdfStatus 只能是 ${PDF_STATUSES.join(' / ')}`);
@@ -194,30 +157,3 @@ export function normalizeGroups(values) {
 export function groupUsage(task, groupId) {
     return Object.values(task.states).filter((state) => state.groupId === groupId).length;
 }
-/** 按必读顺序、年份、标题排序某组的论文。 */
-export function sortGroupPapers(task, papers) {
-    return [...papers].sort((a, b) => {
-        const left = stateOf(task, a.paperId).shortlistOrder;
-        const right = stateOf(task, b.paperId).shortlistOrder;
-        if (left !== undefined || right !== undefined) {
-            if (left === undefined)
-                return 1;
-            if (right === undefined)
-                return -1;
-            if (left !== right)
-                return left - right;
-        }
-        return (b.year ?? 0) - (a.year ?? 0) || a.title.localeCompare(b.title);
-    });
-}
-function normalizeTags(values) {
-    const seen = new Set();
-    for (const raw of values) {
-        const tag = raw.trim().slice(0, MAX_TAG);
-        if (tag !== '')
-            seen.add(tag);
-        if (seen.size >= MAX_TAGS)
-            break;
-    }
-    return [...seen];
-}

package/lib/host/tasks/stats.js

@@ -72,6 +72,7 @@ function countFullText(task, papers) {
         unknown: 0,
         available: 0,
         downloaded: 0,
+        missing: 0,
         htmlOnly: 0,
         paywalled: 0,
         blocked: 0,
@@ -85,6 +86,8 @@ function countFullText(task, papers) {
             coverage.available += 1;
         else if (status === 'downloaded')
             coverage.downloaded += 1;
+        else if (status === 'missing')
+            coverage.missing += 1;
         else if (status === 'paywalled')
             coverage.paywalled += 1;
         else if (status === 'blocked')

package/lib/host/tasks/summary.js

@@ -27,7 +27,7 @@ export function toSummary(task) {
 export function toDetail(task) {
     const states = {};
     for (const [paperId, state] of Object.entries(task.states)) {
-        states[paperId] = { ...state, ...(state.tags === undefined ? {} : { tags: [...state.tags] }) };
+        states[paperId] = { ...state };
     }
     return {
         ...toSummary(task),

package/lib/host/tools.d.ts

@@ -6,7 +6,7 @@
  *   都有效）；只有用户明确要求新任务时才新建。等待最多 25 秒后把任务头部与前
  *   若干条结果交给模型，并明确要求本轮到此为止、只给完善建议、不发起下一轮。
  * - `literature_sources`：列出已接入的数据源与能力，便于模型决定后续策略。
- * - `literature_task`：读取/修改已保存任务（含轮次历史），写入筛读、分组与备注，
+ * - `literature_task`：读取/修改已保存任务（含轮次历史），写入筛读与分组，
  *   做新老对比与统计。
  * - `literature_export`：把任务（按筛选）导出为 CSV / RIS / BibTeX / Markdown 并落盘。
  *

package/lib/host/tools.js

@@ -6,7 +6,7 @@
  *   都有效）；只有用户明确要求新任务时才新建。等待最多 25 秒后把任务头部与前
  *   若干条结果交给模型，并明确要求本轮到此为止、只给完善建议、不发起下一轮。
  * - `literature_sources`：列出已接入的数据源与能力，便于模型决定后续策略。
- * - `literature_task`：读取/修改已保存任务（含轮次历史），写入筛读、分组与备注，
+ * - `literature_task`：读取/修改已保存任务（含轮次历史），写入筛读与分组，
  *   做新老对比与统计。
  * - `literature_export`：把任务（按筛选）导出为 CSV / RIS / BibTeX / Markdown 并落盘。
  *
@@ -139,7 +139,7 @@ const TASK_PARAMETERS = {
         action: {
             type: 'string',
             enum: [...TASK_ACTIONS],
-            description: 'current 读「当前任务」（推荐在执行检索/任务操作前先调用，确认这个对话正在用哪个任务，无需 id）；list 列任务；get 读条件与结果；update 改条件/标题/笔记/分组；run 重跑（仅在用户明确要求进入下一轮时使用）；rounds 读该任务的检索轮次历史；annotate 写筛读/备注；compare 与旧任务对比；stats 读语料统计。',
+            description: 'current 读「当前任务」（推荐在执行检索/任务操作前先调用，确认这个对话正在用哪个任务，无需 id）；list 列任务；get 读条件与结果；update 改条件/标题/笔记/分组；run 重跑（仅在用户明确要求进入下一轮时使用）；rounds 读该任务的检索轮次历史；annotate 写筛读/分组；compare 与旧任务对比；stats 读语料统计。',
         },
         id: { type: 'string', description: '任务 id；除 current / list 外必填。' },
         withTaskId: { type: 'string', description: 'compare 时的基准任务 id。' },
@@ -201,16 +201,13 @@ const TASK_PARAMETERS = {
         papers: {
             type: 'array',
             maxItems: 50,
-            description: 'annotate 时的逐篇写入（筛读 / 分组 / 必读顺序 / 备注 / 标签）。',
+            description: 'annotate 时的逐篇写入（筛读 / 分组）。',
             items: {
                 type: 'object',
                 properties: {
                     paperId: { type: 'string' },
                     screening: { type: 'string', enum: [...SCREENINGS] },
                     groupId: { type: ['string', 'null'] },
-                    shortlistOrder: { type: ['integer', 'null'] },
-                    note: { type: 'string' },
-                    tags: { type: 'array', items: { type: 'string' } },
                 },
                 required: ['paperId'],
                 additionalProperties: false,
@@ -331,7 +328,7 @@ export function literatureTools(service) {
         },
         {
             name: 'literature_task',
-            description: '读取与推进已保存的检索任务。current 读「当前任务」（推荐在执行任何检索/任务操作前先调用，确认这个对话正在用哪个任务；无需 id）；list 列出任务；get 读条件、分组、笔记与结果（可按筛读/分组/检索式/关键词过滤）；update 改标题、条件、任务笔记与分组；rounds 读该任务的检索轮次历史（每轮时间、条件、发起方、命中数与状态）；annotate 批量写入筛读状态、分组、必读顺序、备注与标签；compare 与旧任务按论文身份对比新增/缺失；stats 读语料统计（年份、来源、期刊、作者、类型、语言）。' +
+            description: '读取与推进已保存的检索任务。current 读「当前任务」（推荐在执行任何检索/任务操作前先调用，确认这个对话正在用哪个任务；无需 id）；list 列出任务；get 读条件、分组、笔记与结果（可按筛读/分组/检索式/关键词过滤）；update 改标题、条件、任务笔记与分组；rounds 读该任务的检索轮次历史（每轮时间、条件、发起方、命中数与状态）；annotate 批量写入筛读状态与分组；compare 与旧任务按论文身份对比新增/缺失；stats 读语料统计（年份、来源、期刊、作者、类型、语言）。' +
                 '注意：一个对话只保留一个任务 tab，切换任务由用户在任务列表里完成；run 会在指定任务内开新一轮检索（并把它设为当前任务），与 literature_search 一样受「用户查看结果并明确要求后才能进入下一轮」约束，不能用它绕过该约束自行加搜；也不要用 update 改完条件就立刻 run。适合在检索之后做筛选、整理与汇报。',
             parameters: TASK_PARAMETERS,
             output: TEXT_OUTPUT,
@@ -343,7 +340,7 @@ export function literatureTools(service) {
         },
         {
             name: 'literature_export',
-            description: '把检索任务导出为文件并返回落盘路径。csv 是全量筛读台账（含命中检索式、筛读状态、分组、备注）；ris / bibtex 供 Zotero、EndNote 等文献管理器；md 是分层检索报告（漏斗、按分组的「为什么读」、必读清单、开放获取与 PDF 覆盖率、对比新增）。可按筛读状态、分组、检索式或指定 paperIds 限定范围。',
+            description: '把检索任务导出为文件并返回落盘路径。csv 是全量筛读台账（含命中检索式、筛读状态、分组）；ris / bibtex 供 Zotero、EndNote 等文献管理器；md 是分层检索报告（漏斗、按分组的阅读清单、开放获取与 PDF 覆盖率、对比新增）。可按筛读状态、分组、检索式或指定 paperIds 限定范围。',
             parameters: EXPORT_PARAMETERS,
             output: TEXT_OUTPUT,
             async execute(args) {
@@ -694,23 +691,6 @@ function readAnnotations(value) {
             }
             input.groupId = groupId;
         }
-        if (record['shortlistOrder'] !== undefined) {
-            const order = record['shortlistOrder'];
-            if (order !== null && (typeof order !== 'number' || !Number.isFinite(order))) {
-                throw new Error(`papers[${index}].shortlistOrder 必须是数字或 null`);
-            }
-            input.shortlistOrder = order;
-        }
-        const note = readText(record['note'], `papers[${index}].note`, true);
-        if (note !== undefined)
-            input.note = note;
-        if (record['tags'] !== undefined) {
-            const tags = record['tags'];
-            if (!Array.isArray(tags) || !tags.every((tag) => typeof tag === 'string')) {
-                throw new Error(`papers[${index}].tags 必须是字符串数组`);
-            }
-            input.tags = tags;
-        }
         return input;
     });
 }
@@ -798,7 +778,7 @@ async function runTaskAction(service, args, signal, sessionId) {
         }
         case 'annotate': {
             const result = await service.annotate(requireId(args), args.papers ?? []);
-            return `已写入 ${result.updated} 篇的筛读/备注（任务 id: ${result.taskId}，rev=${result.rev}）。`;
+            return `已写入 ${result.updated} 篇的筛读/分组（任务 id: ${result.taskId}，rev=${result.rev}）。`;
         }
         case 'compare': {
             const report = await service.compare(requireId(args), args.withTaskId ?? '');
@@ -926,7 +906,6 @@ function formatTaskDetail(detail, page, states, groups, outcome) {
         const marks = [
             state?.screening ?? 'unread',
             state?.groupId === undefined ? '' : groupNames.get(state.groupId) ?? state.groupId,
-            state?.shortlistOrder === undefined ? '' : `必读#${state.shortlistOrder}`,
         ].filter((part) => part !== '');
         const meta = [
             paper.authors.slice(0, 4).join(', '),
@@ -938,8 +917,6 @@ function formatTaskDetail(detail, page, states, groups, outcome) {
         lines.push(`${page.offset + index + 1}. [${marks.join('|')}] ${paper.title}`);
         if (meta.length > 0)
             lines.push(`   ${meta.join(' | ')}`);
-        if (state?.note !== undefined && state.note !== '')
-            lines.push(`   备注：${state.note}`);
         if (paper.abstract !== '')
             lines.push(`   摘要：${truncate(paper.abstract, 300)}`);
     });

package/lib/search/oa.d.ts

@@ -6,6 +6,14 @@
 import type { Paper } from './types.js';
 /** 去重后的 PDF 候选地址（顺序即尝试优先级）。 */
 export declare function pdfCandidates(paper: Paper): string[];
+/**
+ * 仓储的 PDF 渲染页：浏览器能打开，后台请求却普遍被拦截。
+ *
+ * 实测 `europepmc.org/articles/...?pdf=render` 返回 403 Cloudflare 页、
+ * `ncbi.nlm.nih.gov/pmc/articles/.../pdf/` 返回 200 但内容是 HTML 落地页。
+ * 它们仍保留为最后兜底，但必须排在所有静态直链与 Unpaywall 结果之后。
+ */
+export declare function isPdfRenderUrl(url: string): boolean;
 /** Europe PMC 的全文 XML 地址；没有 PMCID 时返回 null。 */
 export declare function epmcXmlUrl(paper: Paper): string | null;
 /** Unpaywall 查询（需要联系邮箱，遵守其 polite pool）。 */

package/lib/search/oa.js

@@ -13,6 +13,9 @@ export function pdfCandidates(paper) {
     const candidates = new Set();
     if (paper.pdfUrl !== '')
         candidates.add(paper.pdfUrl);
+    const publisher = publisherPdfUrl(paper.doi);
+    if (publisher !== null)
+        candidates.add(publisher);
     const pmcid = normalizePmcid(paper.ids.pmcid);
     if (pmcid !== '') {
         candidates.add(`${EPMC_ARTICLE}/${pmcid}?pdf=render`);
@@ -22,6 +25,44 @@ export function pdfCandidates(paper) {
         candidates.add(`${ARXIV_PDF}/${paper.ids.arxivId}`);
     return [...candidates];
 }
+/**
+ * 仓储的 PDF 渲染页：浏览器能打开，后台请求却普遍被拦截。
+ *
+ * 实测 `europepmc.org/articles/...?pdf=render` 返回 403 Cloudflare 页、
+ * `ncbi.nlm.nih.gov/pmc/articles/.../pdf/` 返回 200 但内容是 HTML 落地页。
+ * 它们仍保留为最后兜底，但必须排在所有静态直链与 Unpaywall 结果之后。
+ */
+export function isPdfRenderUrl(url) {
+    return url.startsWith(`${EPMC_ARTICLE}/`) || url.startsWith(`${PMC_ARTICLE}/`);
+}
+/**
+ * 部分开放获取出版商的固定 PDF 地址规则。
+ *
+ * Europe PMC / PMC 的渲染页会对后台请求启用 Cloudflare 人机验证（浏览器能打开、
+ * Host 下载却拿到 HTML），因此优先补一条出版商原生 PDF 地址。
+ */
+function publisherPdfUrl(doi) {
+    const value = doi.trim();
+    if (value === '')
+        return null;
+    // BMC / SpringerOpen：https://link.springer.com/content/pdf/<doi>.pdf
+    if (value.startsWith('10.1186/') || value.startsWith('10.1007/')) {
+        return `https://link.springer.com/content/pdf/${encodeURI(value)}.pdf`;
+    }
+    // Frontiers：https://www.frontiersin.org/articles/<doi>/pdf
+    if (value.startsWith('10.3389/')) {
+        return `https://www.frontiersin.org/articles/${encodeURI(value)}/pdf`;
+    }
+    // PLOS ONE
+    if (value.startsWith('10.1371/journal.pone.')) {
+        return `https://journals.plos.org/plosone/article/file?id=${encodeURI(value)}&type=printable`;
+    }
+    // Nature 系列（开放获取文章可下载，订阅文章会落到 HTML 页并继续尝试其它候选）
+    if (value.startsWith('10.1038/')) {
+        return `https://www.nature.com/articles/${encodeURI(value.slice('10.1038/'.length))}.pdf`;
+    }
+    return null;
+}
 /** Europe PMC 的全文 XML 地址；没有 PMCID 时返回 null。 */
 export function epmcXmlUrl(paper) {
     const pmcid = normalizePmcid(paper.ids.pmcid);
@@ -43,13 +84,19 @@ export async function unpaywallPdfCandidates(doi, email, timeoutMs, signal) {
         const body = (await response.json());
         const urls = new Set();
         const best = asRecord(body['best_oa_location']);
-        const bestPdf = asString(best['url_for_pdf']);
-        if (bestPdf !== '')
-            urls.add(bestPdf);
-        for (const raw of asArray(body['oa_locations'])) {
-            const pdf = asString(asRecord(raw)['url_for_pdf']);
-            if (pdf !== '')
+        const locations = [best, ...asArray(body['oa_locations']).map(asRecord)];
+        for (const location of locations) {
+            const pdf = asString(location['url_for_pdf']);
+            if (pdf !== '') {
                 urls.add(pdf);
+                continue;
+            }
+            // 少数仓储只给 `url`，且本身就是 PDF 直链；只收明显是 PDF 的地址，
+            // 避免把落地页塞进候选后又被判成「返回内容不是 PDF」。
+            const landing = asString(location['url']);
+            if (/\.pdf(?:[?#]|$)/iu.test(landing) || /\/pdf\/(?:[?#]|$)/iu.test(landing)) {
+                urls.add(landing);
+            }
         }
         return [...urls];
     }

package/lib/search/types.d.ts

@@ -153,14 +153,20 @@ export interface TaskConditions {
     pageSize: number;
 }
 /** 全文获取状态；`unknown` 表示尚未尝试。 */
-export type PdfStatus = 'unknown' | 'available' | 'downloaded' | 'html-only' | 'paywalled' | 'blocked' | 'failed';
+export type PdfStatus = 'unknown' | 'available' | 'downloaded' | 'missing' | 'html-only' | 'paywalled' | 'blocked' | 'failed';
+/**
+ * PDF 下载失败的根因分类。
+ *
+ * 除了 `failed`（网络/超时/体积等程序故障）之外，其余都属于「后台拿不到、
+ * 但浏览器可能能打开」，界面按此分流，避免把订阅受限误报成功能失败。
+ */
+export type PdfFailureReason = 'no-candidate' | 'blocked' | 'paywalled' | 'not-pdf' | 'failed';
+/** 是否需要引导用户到浏览器手动保存。 */
+export declare function isManualPdfFailure(reason: PdfFailureReason | undefined): boolean;
 /** 论文级人工筛选状态。 */
 export interface PaperState {
     screening: Screening;
     groupId?: string;
-    shortlistOrder?: number;
-    note?: string;
-    tags?: string[];
     pdfStatus?: PdfStatus;
     /** 失败原因（面向用户的一句话）。 */
     pdfError?: string;
@@ -194,7 +200,7 @@ export interface TaskResult {
  * 任务内一次检索（一轮）的元数据快照。
  *
  * 只留「这一轮用什么条件、什么时候跑、跑出多少、结果如何」，**不保存文献列表**：
- * 当前结果永远是最新一轮的 `result.papers`，人工标注按 paperId 跨轮保留。
+ * 当前结果永远是最新一轮的 `result.papers`，筛读状态按 paperId 跨轮保留。
  * 历史轮次用于时间轴回看与「回填条件重跑」。
  */
 export interface SearchRound {
@@ -281,6 +287,8 @@ export interface TaskDetail extends TaskSummary {
     states: Record<string, PaperState>;
     /** 建立任务时继承筛读状态的来源任务。 */
     fromTaskId?: string;
+    /** PDF 实际保存目录（供面板悬停提示）。 */
+    downloadDir?: string;
     result: {
         totalLoaded: number;
         sources: SourceStatus[];
@@ -377,6 +385,7 @@ export interface FullTextCoverage {
     unknown: number;
     available: number;
     downloaded: number;
+    missing: number;
     htmlOnly: number;
     paywalled: number;
     blocked: number;
@@ -388,10 +397,6 @@ export interface AnnotationInput {
     screening?: Screening;
     /** `null` 表示移出分组。 */
     groupId?: string | null;
-    /** `null` 表示清除必读顺序。 */
-    shortlistOrder?: number | null;
-    note?: string;
-    tags?: string[];
     /** 全文状态由 Host 下载/同步流程写入，面板也可显示与筛选。 */
     pdfStatus?: PdfStatus;
     pdfError?: string;
@@ -407,6 +412,8 @@ export interface PdfDownloadResult {
     path?: string;
     url?: string;
     error?: string;
+    /** 失败根因；成功时缺省。 */
+    reason?: PdfFailureReason;
 }
 /** Zotero connector 探测结果。 */
 export interface ZoteroProbeResult {
@@ -448,6 +455,8 @@ export interface PaperDetail {
     paper: Paper;
     state?: PaperState;
     groups: TaskGroup[];
+    /** PDF 实际保存目录（供面板悬停提示）。 */
+    downloadDir?: string;
 }
 /** PubTator 标注的单个实体（按标识符与原文去重）。 */
 export interface PaperEntity {

package/lib/search/types.js

@@ -33,3 +33,7 @@ export const TASK_LANGUAGES = [
     'ita',
     'por',
 ];
+/** 是否需要引导用户到浏览器手动保存。 */
+export function isManualPdfFailure(reason) {
+    return reason !== undefined && reason !== 'failed';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-litsearch",
-  "version": "0.3.0",
+  "version": "0.3.5",
   "description": "Search free scholarly literature sources from DSH. The model can search OpenAlex, Crossref and more with native tools, while you can run the same searches in a sidebar panel and send any paper into the conversation.",
   "keywords": [
     "dsh",