dsh-plugin-litsearch 0.3.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,7 +7,7 @@
  *
  * - 只复制、不删除，旧目录原样保留作备份；
  * - 不覆盖新目录里已有的文件，重复启动不会反复迁移；
- * - 复制失败或校验不通过时回退到旧目录读取，保证任务标注不丢。
+ * - 复制失败或校验不通过时回退到旧目录读取，保证任务数据不丢。
  *
  * PDF 的可读文件由设置项 `pdfRoot` 决定（默认落在当前会话工作目录下的
  * `dsh-litsearch/`），不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs`

package/lib/host/paths.js

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

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,7 +17,11 @@ export interface PdfResolution {
     buffer?: Buffer;
     url?: string;
     error?: string;
+    /** 失败根因；成功时缺省。 */
+    reason?: PdfFailureReason;
 }
+/** 把技术错误整理成「发生了什么 + 下一步做什么」，供界面直接展示。 */
+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;
@@ -40,8 +44,6 @@ 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, workspace?: string): Promise<Buffer | null>;
 /** 清理 PDF 缓存目录。 */
 export declare function cleanupPdfCache(storageRoot: string): Promise<{
     removed: number;

package/lib/host/pdf/store.js

@@ -10,7 +10,7 @@ import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
 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;
@@ -26,6 +26,19 @@ export class PdfFetchError extends Error {
             this.status = status;
     }
 }
+/** 分类对应的下一步指引：后台拿不到时明确告诉用户去浏览器手动保存。 */
+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);
@@ -37,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 };
@@ -64,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 = {}) {
@@ -85,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');
@@ -97,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);
@@ -109,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;
@@ -170,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, workspace) {
-    return readSavedPdf(join(resolvePdfRoot(workspace), readableFilename(paper)));
-}
 /** 清理 PDF 缓存目录。 */
 export async function cleanupPdfCache(storageRoot) {
     const dir = pdfCacheDir(storageRoot);

package/lib/host/router.js

@@ -6,11 +6,15 @@
  * `sec-fetch-site: cross-site`。写端点额外要求自定义头 + JSON content-type，
  * 两者一起让浏览器必须预检，堵掉跨站表单与简单请求。
  */
+import { spawn } from 'node:child_process';
+import { mkdir, stat } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, resolve } from 'node:path';
 import { MAX_LIMIT, ROUTE_PREFIX, SESSION_HEADER, WRITE_HEADER } from '../search/config.js';
 import { SearchError } from '../search/errors.js';
 import { asRecord } from '../search/normalize.js';
 import { isSourceId } from '../search/providers/index.js';
 import { TASK_LANGUAGES } from '../search/types.js';
+import { resolvePdfRoot } from './pdf/store.js';
 import { resolveSessionWorkspace } from './workspace.js';
 const MAX_BODY_BYTES = 1_000_000;
 const SORT_MODES = ['relevance', 'citations', 'year'];
@@ -21,6 +25,7 @@ const PDF_STATUSES = [
     'unknown',
     'available',
     'downloaded',
+    'missing',
     'html-only',
     'paywalled',
     'blocked',
@@ -81,48 +86,6 @@ function sendFile(res, file) {
     });
     res.end(body);
 }
-/** 内联 PDF，支持单段 Range（预览器会按需拉取）。 */
-function sendPdf(req, res, buffer, filename) {
-    const total = buffer.length;
-    const disposition = `inline; filename*=UTF-8''${encodeURIComponent(filename)}`;
-    const range = req.headers.range;
-    if (range === undefined) {
-        res.writeHead(200, {
-            'content-type': 'application/pdf',
-            'content-length': total,
-            'content-disposition': disposition,
-            'accept-ranges': 'bytes',
-            'cache-control': 'no-store',
-        });
-        res.end(buffer);
-        return;
-    }
-    const match = /^bytes=(\d*)-(\d*)$/u.exec(range.trim());
-    const start = match?.[1] === '' ? Number.NaN : Number(match?.[1]);
-    const end = match?.[2] === '' ? Number.NaN : Number(match?.[2]);
-    if (match === null || (!Number.isFinite(start) && !Number.isFinite(end))) {
-        res.writeHead(416, { 'content-range': `bytes */${total}`, 'cache-control': 'no-store' });
-        res.end();
-        return;
-    }
-    const from = Number.isFinite(start) ? Math.max(0, start) : Math.max(0, total - (end || 0));
-    const to = Number.isFinite(end) ? Math.min(end, total - 1) : total - 1;
-    if (from > to || from >= total) {
-        res.writeHead(416, { 'content-range': `bytes */${total}`, 'cache-control': 'no-store' });
-        res.end();
-        return;
-    }
-    const chunk = buffer.subarray(from, to + 1);
-    res.writeHead(206, {
-        'content-type': 'application/pdf',
-        'content-length': chunk.length,
-        'content-range': `bytes ${from}-${to}/${total}`,
-        'content-disposition': disposition,
-        'accept-ranges': 'bytes',
-        'cache-control': 'no-store',
-    });
-    res.end(chunk);
-}
 function sendHtml(res, status, html) {
     res.writeHead(status, {
         'content-type': 'text/html; charset=utf-8',
@@ -130,6 +93,52 @@ function sendHtml(res, status, html) {
     });
     res.end(html);
 }
+/**
+ * 在系统文件管理器中定位文件：macOS Finder、Windows 资源管理器、Linux 桌面。
+ * 只接受已存在的 PDF 文件或目录（批量下载的「打开下载目录」用后者），
+ * 避免这个端点被当成任意路径探测。
+ */
+async function revealInFileManager(rawPath, downloadRoot) {
+    const target = resolve(rawPath);
+    let info = await stat(target).catch(() => null);
+    // 下载目录可能一篇都还没下过：打开前补建，避免点「打开下载目录」毫无反应。
+    if (info === null && downloadRoot !== undefined && resolve(downloadRoot) === target) {
+        await mkdir(target, { recursive: true });
+        info = await stat(target).catch(() => null);
+    }
+    if (info === null)
+        throw new SearchError('not_found', '文件不存在或已被移动');
+    if (info.isDirectory()) {
+        const [command, args] = process.platform === 'darwin'
+            ? ['open', [target]]
+            : process.platform === 'win32'
+                ? ['explorer.exe', [target]]
+                : ['xdg-open', [target]];
+        await spawnDetached(command, args);
+        return { path: target };
+    }
+    if (!info.isFile() || extname(target).toLowerCase() !== '.pdf') {
+        throw new SearchError('bad_request', '只能定位 PDF 文件或下载目录');
+    }
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', ['-R', target]]
+        : process.platform === 'win32'
+            ? ['explorer.exe', [`/select,${target}`]]
+            : ['xdg-open', [dirname(target)]];
+    await spawnDetached(command, args);
+    return { path: target };
+}
+/** 启动系统命令后立即脱离，不等待它的生命周期。 */
+async function spawnDetached(command, args) {
+    await new Promise((settle, rejectSpawn) => {
+        const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+        child.once('error', rejectSpawn);
+        child.once('spawn', () => {
+            child.unref();
+            settle();
+        });
+    });
+}
 function sendHtmlError(res, error) {
     const { status, error: apiError } = toApiError(error);
     sendHtml(res, status === 500 ? 502 : status, `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><title>全文不可用</title></head><body style="font:14px/1.7 -apple-system,'PingFang SC',sans-serif;padding:16px"><p>全文不可用：${escapeHtml(apiError.message)}</p></body></html>`);
@@ -300,26 +309,6 @@ function readAnnotations(value) {
             if (groupId !== undefined)
                 input.groupId = groupId;
         }
-        if (record['shortlistOrder'] === null)
-            input.shortlistOrder = null;
-        else if (record['shortlistOrder'] !== undefined) {
-            const order = readInt(record['shortlistOrder'], 'shortlistOrder', 0, 100_000);
-            if (order !== undefined)
-                input.shortlistOrder = order;
-        }
-        if (record['note'] !== undefined) {
-            if (typeof record['note'] !== 'string') {
-                throw new SearchError('bad_request', 'note 必须是字符串');
-            }
-            input.note = record['note'].slice(0, 4_000);
-        }
-        if (record['tags'] !== undefined) {
-            const tags = readStringArray(record['tags'], 'tags', 20, 40);
-            if (tags !== undefined && tags !== null)
-                input.tags = tags;
-            else if (tags === null)
-                input.tags = [];
-        }
         return input;
     });
 }
@@ -590,7 +579,7 @@ async function handleTasks(service, req, res, seg, params, sessionId) {
     const action = seg[2];
     if (action === undefined) {
         if (req.method === 'GET') {
-            ok(res, await service.getDetail(id));
+            ok(res, await service.getDetail(id, await resolveSessionWorkspace(sessionId)));
             return;
         }
         if (req.method === 'PATCH') {
@@ -664,7 +653,7 @@ async function handleTasks(service, req, res, seg, params, sessionId) {
                 fail(res, 405, 'bad_request', '论文详情仅支持 GET');
                 return;
             }
-            ok(res, await service.paperDetail(id, paperId));
+            ok(res, await service.paperDetail(id, paperId, await resolveSessionWorkspace(sessionId)));
             return;
         }
         if (op === 'entities') {
@@ -675,27 +664,20 @@ async function handleTasks(service, req, res, seg, params, sessionId) {
             ok(res, await service.entities(id, paperId));
             return;
         }
-        if (op === 'download') {
+        if (op === 'recheck') {
             if (req.method !== 'POST') {
-                fail(res, 405, 'bad_request', 'download 仅支持 POST');
+                fail(res, 405, 'bad_request', 'recheck 仅支持 POST');
                 return;
             }
-            ok(res, await service.downloadPdf(id, paperId, await resolveSessionWorkspace(sessionId)));
+            ok(res, await service.recheckPdf(id, paperId));
             return;
         }
-        if (op === 'pdf') {
-            if (req.method !== 'GET') {
-                fail(res, 405, 'bad_request', 'pdf 仅支持 GET');
+        if (op === 'download') {
+            if (req.method !== 'POST') {
+                fail(res, 405, 'bad_request', 'download 仅支持 POST');
                 return;
             }
-            try {
-                const file = await service.previewPdf(id, paperId, await resolveSessionWorkspace(sessionId));
-                sendPdf(req, res, file.buffer, file.filename);
-            }
-            catch (error) {
-                const { status, error: apiError } = toApiError(error);
-                fail(res, status === 500 ? 502 : status, apiError.code, apiError.message);
-            }
+            ok(res, await service.downloadPdf(id, paperId, await resolveSessionWorkspace(sessionId)));
             return;
         }
         if (op === 'fulltext') {
@@ -802,6 +784,26 @@ export function createHandler(service) {
                 ok(res, await service.eventsSince(Number.isFinite(sinceRev) ? sinceRev : 0));
                 return;
             }
+            if (head === 'files') {
+                if (seg[1] !== 'reveal') {
+                    fail(res, 404, 'not_found', `未知文件操作 ${seg[1] ?? ''}`);
+                    return;
+                }
+                if (req.method !== 'POST') {
+                    fail(res, 405, 'bad_request', 'reveal 仅支持 POST');
+                    return;
+                }
+                const body = await readJsonBody(req);
+                const path = readString(body['path'], 'path', 4096);
+                if (path === undefined || path === '') {
+                    throw new SearchError('bad_request', '缺少 path 参数');
+                }
+                if (!isAbsolute(path))
+                    throw new SearchError('bad_request', 'path 必须是绝对路径');
+                const workspace = await resolveSessionWorkspace(readSessionId(req, url.searchParams));
+                ok(res, await revealInFileManager(path, resolvePdfRoot(workspace)));
+                return;
+            }
             if (head === 'settings') {
                 if (seg[1] === 'probe' && req.method === 'POST') {
                     const source = readString((await readJsonBody(req))['source'], 'source', 40);

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

@@ -89,7 +89,7 @@ export declare class TaskService {
     eventsSince(sinceRev: number): Promise<EventsPage>;
     list(filter?: TaskListFilter): Promise<TaskSummary[]>;
     get(id: string): Promise<SearchTask>;
-    getDetail(id: string): Promise<TaskDetail>;
+    getDetail(id: string, workspace?: string): Promise<TaskDetail>;
     /** 任务内轮次历史（时间升序、深拷贝）。 */
     getRounds(id: string): Promise<SearchRound[]>;
     /**
@@ -129,7 +129,7 @@ export declare class TaskService {
     cancel(id: string): Promise<SearchTask>;
     results(id: string, filter?: ResultsFilter): Promise<ResultsPage>;
     stats(id: string, filter?: PaperFilter, scope?: 'task' | 'filtered'): Promise<TaskStatsReport>;
-    /** 写入筛读 / 分组 / 必读 / 备注；返回新的 rev 与命中条数。 */
+    /** 写入筛读 / 分组；返回新的 rev 与命中条数。 */
     annotate(id: string, inputs: readonly AnnotationInput[], expectedRev?: number): Promise<AnnotationResult>;
     compare(id: string, withTaskId: string): Promise<CompareResult>;
     /** 生成导出内容；`paperIds` 为空表示按当前筛选导出全部。 */
@@ -142,17 +142,19 @@ export declare class TaskService {
     }>;
     /** 设置页清理：任务文件与 PDF 缓存。 */
     cleanup(scope: CleanupScope): Promise<CleanupResult>;
+    /**
+     * 「查看已下载」前的存在性检查：页面加载后文件可能被删除或移走。
+     * 缺失时把状态改为 `missing` 并广播，所有面板随即显示「下载文件已删除」。
+     */
+    recheckPdf(id: string, paperId: string): Promise<{
+        exists: boolean;
+    }>;
     /** 下载单篇 PDF；失败时写入失败状态，若有 EPMC 全文则降级为 html-only。 */
     downloadPdf(id: string, paperId: string, workspace?: string): Promise<PdfDownloadResult>;
-    /** PDF 预览：优先用已落地文件；没有则临时抓取一次但不落盘。 */
-    previewPdf(id: string, paperId: string, workspace?: string): Promise<{
-        buffer: Buffer;
-        filename: string;
-    }>;
     /** Europe PMC 全文（JATS → 只含安全标签的 HTML）。 */
     fullText(id: string, paperId: string): Promise<string>;
     /** 单篇论文详情：独立论文页使用，含任务标题与分组。 */
-    paperDetail(id: string, paperId: string): Promise<PaperDetail>;
+    paperDetail(id: string, paperId: string, workspace?: string): Promise<PaperDetail>;
     /** PubTator3 实体标注；无 PMID 时明确告知不可标注。 */
     entities(id: string, paperId: string, signal?: AbortSignal): Promise<PaperEntities>;
     /** 测试 Zotero connector 是否可达，并返回当前选中的分类。 */