dsh-plugin-litsearch 0.3.0 → 0.4.0

package/lib/host/events.d.ts

@@ -5,15 +5,23 @@
  * 的 globalRev」日志；客户端按 `sinceRev` 轮询拿增量。globalRev 只在宿主进程内
  * 单调递增，重启后归零 —— 客户端发现 `sinceRev` 比服务端大就以 `reset` 重新同步。
  */
-import type { EventsPage, TaskSummary } from '../search/types.js';
+import type { DownloadCommand, EventsPage, TaskSummary, ZoteroCommand } from '../search/types.js';
 export declare class TaskEvents {
     private rev;
     private readonly entries;
     private focus;
+    /** 下载指令日志：数组而非单值，两次轮询之间连发多条也不会互相覆盖。 */
+    private readonly downloadEntries;
+    /** Zotero 同步指令日志，与下载并列，互不覆盖。 */
+    private readonly zoteroEntries;
     get currentRev(): number;
     publish(summary: TaskSummary): void;
     /** 请求客户端把某个任务 tab 打开/切到前台（面板关着时重新打开）。 */
     requestFocus(taskId: string, title: string, sessionId?: string): void;
+    /** 下发一条模型批量下载指令；与 focus 一样推进 globalRev 走增量轮询。 */
+    publishDownload(command: DownloadCommand): void;
+    /** 下发一条模型 Zotero 同步指令；与下载指令一样推进 globalRev 走增量轮询。 */
+    publishZotero(command: ZoteroCommand): void;
     remove(id: string): void;
     since(sinceRev: number): EventsPage;
 }

package/lib/host/events.js

@@ -5,10 +5,17 @@
  * 的 globalRev」日志；客户端按 `sinceRev` 轮询拿增量。globalRev 只在宿主进程内
  * 单调递增，重启后归零 —— 客户端发现 `sinceRev` 比服务端大就以 `reset` 重新同步。
  */
+/** 事件日志里最多保留多少条模型指令，避免长时间运行无限增长。 */
+const MAX_DOWNLOAD_ENTRIES = 50;
+const MAX_ZOTERO_ENTRIES = 50;
 export class TaskEvents {
     rev = 0;
     entries = new Map();
     focus;
+    /** 下载指令日志：数组而非单值，两次轮询之间连发多条也不会互相覆盖。 */
+    downloadEntries = [];
+    /** Zotero 同步指令日志，与下载并列，互不覆盖。 */
+    zoteroEntries = [];
     get currentRev() {
         return this.rev;
     }
@@ -27,17 +34,42 @@ export class TaskEvents {
             ...(sessionId === undefined ? {} : { sessionId }),
         };
     }
+    /** 下发一条模型批量下载指令；与 focus 一样推进 globalRev 走增量轮询。 */
+    publishDownload(command) {
+        this.rev += 1;
+        this.downloadEntries.push({ globalRev: this.rev, command });
+        if (this.downloadEntries.length > MAX_DOWNLOAD_ENTRIES) {
+            this.downloadEntries.splice(0, this.downloadEntries.length - MAX_DOWNLOAD_ENTRIES);
+        }
+    }
+    /** 下发一条模型 Zotero 同步指令；与下载指令一样推进 globalRev 走增量轮询。 */
+    publishZotero(command) {
+        this.rev += 1;
+        this.zoteroEntries.push({ globalRev: this.rev, command });
+        if (this.zoteroEntries.length > MAX_ZOTERO_ENTRIES) {
+            this.zoteroEntries.splice(0, this.zoteroEntries.length - MAX_ZOTERO_ENTRIES);
+        }
+    }
     remove(id) {
         this.entries.delete(id);
         if (this.focus?.taskId === id)
             this.focus = undefined;
+        for (let index = this.downloadEntries.length - 1; index >= 0; index -= 1) {
+            if (this.downloadEntries[index]?.command.taskId === id)
+                this.downloadEntries.splice(index, 1);
+        }
+        for (let index = this.zoteroEntries.length - 1; index >= 0; index -= 1) {
+            if (this.zoteroEntries[index]?.command.taskId === id)
+                this.zoteroEntries.splice(index, 1);
+        }
     }
     since(sinceRev) {
         if (!Number.isFinite(sinceRev) || sinceRev < 0) {
-            return { rev: this.rev, reset: true, tasks: [] };
+            // 宿主重启 / 客户端状态错乱：重新对齐，不重放历史模型指令。
+            return { rev: this.rev, reset: true, tasks: [], downloads: [], zotero: [] };
         }
         if (sinceRev > this.rev) {
-            return { rev: this.rev, reset: true, tasks: [] };
+            return { rev: this.rev, reset: true, tasks: [], downloads: [], zotero: [] };
         }
         const tasks = [...this.entries.values()]
             .filter((entry) => entry.globalRev > sinceRev)
@@ -53,6 +85,21 @@ export class TaskEvents {
                     : { sessionId: this.focus.sessionId }),
             }
             : undefined;
-        return { rev: this.rev, reset: false, tasks, ...(focus === undefined ? {} : { focus }) };
+        const downloads = this.downloadEntries
+            .filter((entry) => entry.globalRev > sinceRev)
+            .sort((a, b) => a.globalRev - b.globalRev)
+            .map((entry) => entry.command);
+        const zotero = this.zoteroEntries
+            .filter((entry) => entry.globalRev > sinceRev)
+            .sort((a, b) => a.globalRev - b.globalRev)
+            .map((entry) => entry.command);
+        return {
+            rev: this.rev,
+            reset: false,
+            tasks,
+            ...(focus === undefined ? {} : { focus }),
+            downloads,
+            zotero,
+        };
     }
 }

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);