dsh-plugin-litsearch 0.3.0 → 0.4.0

package/lib/host/tasks/download.js

@@ -0,0 +1,274 @@
+/**
+ * 模型下载指令的范围解析（纯函数，便于单测）。
+ *
+ * 模型跑在 Host 侧，看不到右侧栏翻到第几页、用了什么筛选。范围统一由视图
+ * 快照 + 服务端 `filterPapers` 算准，并逐个与任务结果取交集，最终只把一份
+ * 「已校验的 paperId 清单」交给 Client —— 浏览器不再解析任何条件，也不会
+ * 出现「模型理解的筛选」与「界面筛选」两套口径。
+ */
+/**
+ * 每页篇数的兜底值，与 `types.ts` 的 `RESULT_PAGE_SIZE`（面板分页粒度）一致。
+ *
+ * 本文件要能被 `node --test` 直接加载，因此不做任何运行时模块导入（`.js`
+ * 后缀在同环境里无法回落到 `.ts`）；真正的每页条数总由调用方通过视图快照
+ * 传入，这里只兜底。`test/download-scope.test.ts` 会断言它仍是 20。
+ */
+const FALLBACK_PAGE_SIZE = 20;
+/**
+ * 与 `types.ts` 的 `TASK_LANGUAGES` 一致。这里刻意只做类型导入、不产生运行时
+ * 模块依赖：`src` 源码可被 `node --test` 直接加载，Host 构建产物仍走 `.js`。
+ */
+const LANGUAGE_VALUES = [
+    'any',
+    'eng',
+    'chi',
+    'jpn',
+    'kor',
+    'fre',
+    'ger',
+    'spa',
+    'rus',
+    'ita',
+    'por',
+];
+const SCREENING_VALUES = ['unread', 'read', 'included', 'excluded'];
+const PDF_STATUS_VALUES = [
+    'unknown',
+    'available',
+    'downloaded',
+    'missing',
+    'html-only',
+    'paywalled',
+    'blocked',
+    'failed',
+];
+/**
+ * 把视图快照的扁平筛选投影收窄回 `PaperFilter`。
+ *
+ * 快照来自 Client 的 `ResultsQuery`，键名与筛选口径一致；这里只按白名单取，
+ * 未知键与非法枚举值一律忽略，避免模型/前端写入任意字段影响后台过滤。
+ */
+export function toPaperFilter(raw) {
+    const text = (key) => {
+        const value = raw[key];
+        return typeof value === 'string' && value !== '' ? value : undefined;
+    };
+    const number = (key) => {
+        const value = raw[key];
+        return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+    };
+    const flag = (key) => (raw[key] === true ? true : undefined);
+    const oneOf = (key, values) => {
+        const value = raw[key];
+        return typeof value === 'string' ? values.find((item) => item === value) : undefined;
+    };
+    return {
+        source: text('source'),
+        q: text('q'),
+        queryId: text('queryId'),
+        type: text('type'),
+        venue: text('venue'),
+        author: text('author'),
+        groupId: text('groupId'),
+        yearFrom: number('yearFrom'),
+        yearTo: number('yearTo'),
+        openAccessOnly: flag('openAccessOnly'),
+        hasPdf: flag('hasPdf'),
+        missingFullText: flag('missingFullText'),
+        newOnly: flag('newOnly'),
+        screening: oneOf('screening', SCREENING_VALUES),
+        language: oneOf('language', LANGUAGE_VALUES),
+        pdfStatus: oneOf('pdfStatus', PDF_STATUS_VALUES),
+    };
+}
+/** 视图筛选打底，工具显式字段覆盖同名项；显式值为 undefined 的不覆盖。 */
+export function mergeDownloadFilter(base, explicit) {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(explicit)) {
+        if (value === undefined)
+            continue;
+        Object.assign(merged, { [key]: value });
+    }
+    return merged;
+}
+/**
+ * 把「第 4–5 页」解析成 paperId 清单。
+ *
+ * 页码语义固定在「用户屏幕上那一页」：每页 `pageSize` 条（面板恒为 20）。
+ * **前置条件**：`matched` / `viewMatched` 必须已按界面排序排好（调用方用
+ * `filter.sortPapers`），否则切出来的页与面板不一致。
+ *
+ * `pageBase='view'` 时先切页、再与附加条件取交集，这样「第二页里有 PDF 的
+ * 文献」不会因为加了 `hasPdf` 而把页面整体前移。
+ */
+export function resolvePageWindow(options) {
+    const pageSize = Math.max(1, Math.floor(options.pageSize ?? FALLBACK_PAGE_SIZE));
+    const base = options.pageBase === 'view' ? options.viewMatched : options.matched;
+    const pageCount = Math.max(1, Math.ceil(base.length / pageSize));
+    const outOfRange = [];
+    const seen = new Set();
+    const paperIds = [];
+    for (const page of [...options.pages].sort((a, b) => a - b)) {
+        const index = Math.floor(page) - 1;
+        if (index < 0 || page > pageCount) {
+            outOfRange.push(page);
+            continue;
+        }
+        const start = index * pageSize;
+        for (const paper of base.slice(start, start + pageSize)) {
+            if (seen.has(paper.paperId))
+                continue;
+            seen.add(paper.paperId);
+            paperIds.push(paper.paperId);
+        }
+    }
+    return { paperIds, pageSize, pageCount, outOfRange };
+}
+/**
+ * 解析范围 → 已校验的 paperId 清单。
+ *
+ * `ids` 按模型给定顺序、`currentPage` 按用户当前页顺序，其余按任务结果原序；
+ * 每种范围都会再与 `filterPapers` 的结果取交集，因此叠加 `hasPdf`、年份等
+ * 条件时与界面口径完全一致。全量直接用纯函数过滤，不受 `/results` 的 200
+ * 条分页上限约束。
+ */
+export function resolveDownloadScope(task, options) {
+    const byId = new Map(task.result.papers.map((paper) => [paper.paperId, paper]));
+    const eligible = new Set(options.matched.map((paper) => paper.paperId));
+    let ordered;
+    let pageCount;
+    let outOfRange;
+    switch (options.scope) {
+        case 'ids': {
+            const seen = new Set();
+            ordered = [];
+            for (const raw of options.explicitIds ?? []) {
+                const id = raw.trim();
+                if (id === '' || seen.has(id))
+                    continue;
+                seen.add(id);
+                ordered.push(id);
+            }
+            break;
+        }
+        case 'currentPage': {
+            ordered = [...(options.pagePaperIds ?? options.snapshot?.pagePaperIds ?? [])];
+            break;
+        }
+        case 'pages': {
+            const window = resolvePageWindow({
+                pages: options.pages ?? [],
+                pageBase: options.pageBase ?? 'view',
+                matched: options.matched,
+                viewMatched: options.viewMatched ?? options.matched,
+                ...(options.pageSize === undefined ? {} : { pageSize: options.pageSize }),
+            });
+            ordered = window.paperIds;
+            pageCount = window.pageCount;
+            outOfRange = window.outOfRange;
+            break;
+        }
+        default: {
+            ordered = options.matched.map((paper) => paper.paperId);
+            break;
+        }
+    }
+    const paperIds = [];
+    const items = [];
+    for (const id of ordered) {
+        if (!eligible.has(id))
+            continue;
+        const paper = byId.get(id);
+        if (paper === undefined)
+            continue;
+        paperIds.push(id);
+        const meta = [paper.venue, paper.year === null ? '' : String(paper.year)]
+            .filter((part) => part !== '')
+            .join(' · ');
+        items.push({
+            paperId: id,
+            title: paper.title,
+            source: paper.hitSources[0]?.source ?? paper.source,
+            ...(meta === '' ? {} : { meta }),
+        });
+    }
+    return {
+        paperIds,
+        items,
+        ignored: ordered.length - paperIds.length,
+        scopeLabel: buildScopeLabel(options.scope, paperIds.length, options),
+        ...(pageCount === undefined ? {} : { pageCount }),
+        ...(outOfRange === undefined ? {} : { outOfRange }),
+    };
+}
+/** 生成给弹窗展示的中文范围说明（含篇数）；Client 只显示、不翻译、不再解析。 */
+export function buildScopeLabel(scope, count, options) {
+    const parts = [];
+    switch (scope) {
+        case 'ids':
+            parts.push('指定文献');
+            break;
+        case 'currentPage':
+            parts.push(`当前页（第 ${(options.snapshot?.pageIndex ?? 0) + 1} 页）`);
+            break;
+        case 'pages':
+            parts.push(`第 ${describePages(options.pages ?? [])} 页`);
+            break;
+        case 'currentView':
+            parts.push('当前筛选全部');
+            break;
+        case 'all':
+            parts.push('整个任务全部文献');
+            break;
+        case 'group':
+            parts.push(`分组「${options.groupName ?? options.filter.groupId ?? ''}」`);
+            break;
+        case 'filters':
+            parts.push('按条件筛选');
+            break;
+    }
+    const filter = options.filter;
+    if (filter.hasPdf === true)
+        parts.push('仅含 PDF 直链或已下载');
+    if (filter.openAccessOnly === true)
+        parts.push('仅开放获取');
+    if (filter.q !== undefined && filter.q !== '')
+        parts.push(`关键词「${filter.q}」`);
+    if (filter.groupId !== undefined && scope !== 'group')
+        parts.push(`分组 ${filter.groupId}`);
+    if (filter.yearFrom !== undefined || filter.yearTo !== undefined) {
+        parts.push(`${filter.yearFrom ?? '不限'}–${filter.yearTo ?? '不限'} 年`);
+    }
+    if (filter.source !== undefined)
+        parts.push(`来源 ${filter.source}`);
+    if (filter.screening !== undefined)
+        parts.push(`筛读 ${filter.screening}`);
+    if (filter.pdfStatus !== undefined)
+        parts.push(`全文状态 ${filter.pdfStatus}`);
+    if (filter.venue !== undefined && filter.venue !== '')
+        parts.push(`出处 ${filter.venue}`);
+    if (filter.author !== undefined && filter.author !== '')
+        parts.push(`作者 ${filter.author}`);
+    return `${parts.join(' · ')} · 共 ${count} 篇`;
+}
+/** 页码列表 → 可读文案：`[2]` → `2`，`[4,5,6]` → `4–6`，`[2,5]` → `2、5`。 */
+export function describePages(pages) {
+    const sorted = [...new Set(pages)].sort((a, b) => a - b);
+    if (sorted.length === 0)
+        return '';
+    const chunks = [];
+    let start = sorted[0];
+    let prev = sorted[0];
+    for (let index = 1; index < sorted.length; index += 1) {
+        const page = sorted[index];
+        if (page === prev + 1) {
+            prev = page;
+            continue;
+        }
+        chunks.push(start === prev ? String(start) : `${start}–${prev}`);
+        start = page;
+        prev = page;
+    }
+    chunks.push(start === prev ? String(start) : `${start}–${prev}`);
+    return chunks.join('、');
+}

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

@@ -3,7 +3,7 @@
  *
  * 任何新筛选条件都必须先加到这里，避免列表与统计出现两套过滤逻辑。
  */
-import type { Paper, PdfStatus, Screening, SearchTask, TaskLanguage } from '../../search/types.js';
+import type { Paper, PdfStatus, Screening, SearchTask, SortMode, TaskLanguage } from '../../search/types.js';
 export interface PaperFilter {
     source?: string;
     yearFrom?: number;
@@ -35,6 +35,13 @@ export interface PaperFilter {
 }
 export declare function filterPapers(task: SearchTask, filter?: PaperFilter): Paper[];
 export declare function screeningOf(task: SearchTask, paper: Paper): Screening;
+/**
+ * 结果排序：`/results`、`/stats` 与模型侧的按页取数共用这一份口径。
+ *
+ * `relevance` 保持上游合并后的原序（不做二次排序）；被引/年份缺失的排在最后，
+ * 与面板看到的顺序一致。原地排序，调用方传入副本。
+ */
+export declare function sortPapers(papers: Paper[], sort: SortMode | undefined): void;
 /** 有效全文状态：没有人工/下载记录时，上游给的 PDF 直链视为可用。 */
 export declare function pdfStatusOf(task: SearchTask, paper: Paper): PdfStatus;
 export declare function matchesLanguage(paper: {

package/lib/host/tasks/filter.js

@@ -62,6 +62,20 @@ export function filterPapers(task, filter = {}) {
 export function screeningOf(task, paper) {
     return task.states[paper.paperId]?.screening ?? 'unread';
 }
+/**
+ * 结果排序：`/results`、`/stats` 与模型侧的按页取数共用这一份口径。
+ *
+ * `relevance` 保持上游合并后的原序（不做二次排序）；被引/年份缺失的排在最后，
+ * 与面板看到的顺序一致。原地排序，调用方传入副本。
+ */
+export function sortPapers(papers, sort) {
+    if (sort === 'citations') {
+        papers.sort((a, b) => (b.citedBy ?? -1) - (a.citedBy ?? -1));
+    }
+    else if (sort === 'year') {
+        papers.sort((a, b) => (b.year ?? 0) - (a.year ?? 0));
+    }
+}
 /** 有效全文状态：没有人工/下载记录时，上游给的 PDF 直链视为可用。 */
 export function pdfStatusOf(task, paper) {
     const recorded = task.states[paper.paperId]?.pdfStatus;

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

@@ -4,7 +4,7 @@
  * 负责校验/规范化任务条件、维护内存与磁盘状态、串行化执行并广播 rev。
  * 模型工具与面板 HTTP 路由都只调用这里，保证两边操作同一份状态。
  */
-import type { AnnotationInput, AnnotationResult, CleanupResult, CleanupScope, CompareResult, EventsPage, ExportFile, ExportFormat, HealthInfo, PaperDetail, PaperEntities, PdfDownloadResult, ProbeResult, QueryBlock, ResultsPage, SearchRound, SearchTask, SortMode, SourceId, StorageProbeResult, TaskDetail, TaskGroup, TaskLanguage, TaskOrigin, TaskStatsReport, TaskSummary, ZoteroProbeResult, ZoteroSyncResult } from '../../search/types.js';
+import type { AnnotationInput, AnnotationResult, CleanupResult, CleanupScope, CompareResult, DownloadCommand, EventsPage, ExportFile, ExportFormat, HealthInfo, PaperDetail, PaperEntities, PdfDownloadResult, ProbeResult, QueryBlock, ResultsPage, SearchRound, SearchTask, SortMode, SourceId, StorageProbeResult, TaskDetail, TaskGroup, TaskLanguage, TaskOrigin, TaskStatsReport, TaskSummary, ViewSnapshot, ZoteroCommand, ZoteroProbeResult, ZoteroSyncResult, ZoteroTargetsResult } from '../../search/types.js';
 import { type PaperFilter } from './filter.js';
 export interface QueryInput {
     name?: string;
@@ -62,6 +62,13 @@ export declare class TaskService {
     private readonly store;
     private readonly events;
     private readonly runner;
+    /**
+     * 每个会话最近一次的右侧栏视图快照（内存、不落盘）。
+     *
+     * 模型工具跑在 Host 侧看不到界面，靠它把「当前页」「当前筛选全部」算准；
+     * 宿主重启即失效，与事件日志 rev 的生命周期一致。
+     */
+    private readonly views;
     /**
      * 全局「当前任务」：最后一次使用或打开的任务。
      *
@@ -89,7 +96,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[]>;
     /**
@@ -103,6 +110,17 @@ export declare class TaskService {
     setCurrentTask(id: string): void;
     /** 请求客户端打开/聚焦某任务 tab（面板被关掉时重新打开）。 */
     focusTask(id: string, title: string, sessionId?: string): void;
+    /** 下发一条模型批量下载指令；右侧栏轮询 /events 拿增量后自行执行。 */
+    publishDownloadCommand(command: DownloadCommand): void;
+    /** 下发一条模型批量存入 Zotero 指令；与下载指令走独立的事件日志。 */
+    publishZoteroCommand(command: ZoteroCommand): void;
+    /**
+     * 面板上报当前视图。会话 id 以请求头为准覆盖 body，防止伪造别的会话的视图；
+     * 时间也由 Host 重置，避免客户端时钟偏差影响过期判断。
+     */
+    saveViewSnapshot(sessionId: string, snapshot: ViewSnapshot): void;
+    /** 取该会话在该任务上的最近视图；过期、跨任务或 rev 超前都视为不可信。 */
+    getViewSnapshot(sessionId: string | undefined, taskId: string): Promise<ViewSnapshot | undefined>;
     private persistCurrent;
     /** 用户从任务列表点开某任务 = 进入该任务，之后的模型检索默认落在这里。 */
     activate(id: string, workspace?: string): Promise<SearchTask>;
@@ -129,7 +147,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,23 +160,33 @@ 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 是否可达，并返回当前选中的分类。 */
     zoteroProbe(): Promise<ZoteroProbeResult>;
-    /** 把选中论文同步到 Zotero（含本地 PDF 附件）。 */
-    zoteroSync(id: string, paperIds?: readonly string[], workspace?: string): Promise<ZoteroSyncResult>;
+    /** 可写入的 Zotero 库与分类，供同步弹窗选择目标目录。 */
+    zoteroTargets(): Promise<ZoteroTargetsResult>;
+    /** 把选中论文同步到 Zotero（含本地 PDF 附件），并记录每篇的同步状态。 */
+    zoteroSync(id: string, paperIds?: readonly string[], workspace?: string, target?: {
+        id: string;
+        name?: string;
+        filesEditable?: boolean;
+    }): Promise<ZoteroSyncResult>;
+    /** 记录单篇文献的 Zotero 同步状态；与 PDF 状态一样写回任务并广播。 */
+    private setZoteroState;
     /** 下载目录可写性测试（设置页）。 */
     storageProbe(workspace?: string): Promise<StorageProbeResult>;
     private ensureLocalPdf;
@@ -167,6 +195,11 @@ export declare class TaskService {
     probe(source: SourceId): Promise<ProbeResult>;
     private tryGet;
     private baseInfo;
+    /**
+     * 供模型下载工具复用：`newOnly` 需要基准任务的论文集合才能与界面口径一致。
+     * 直接暴露给工具层，避免下载范围解析和 `/results` 出现两套过滤逻辑。
+     */
+    resolveDownloadFilter(id: string, filter: PaperFilter): Promise<PaperFilter>;
     /** `newOnly` 需要基准任务的论文集合；基准已删除时忽略该条件。 */
     private withBaseFilter;
     dispose(): void;