dsh-plugin-litsearch 0.3.5 → 0.4.0

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;
     /**
      * 全局「当前任务」：最后一次使用或打开的任务。
      *
@@ -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>;
@@ -159,8 +177,16 @@ export declare class TaskService {
     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;
@@ -169,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;

package/lib/host/tasks/service.js

@@ -7,7 +7,7 @@
 import { randomUUID } from 'node:crypto';
 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 { MAX_LIMIT, getSettings } from '../../search/config.js';
 import { SearchError } from '../../search/errors.js';
 import { cooldownUntil, sourceHealthList } from '../../search/health.js';
 import { PROVIDER_INFOS } from '../../search/providers/index.js';
@@ -21,7 +21,7 @@ import { cleanupPdfCache, epmcFullTextAvailable, persistPdf, probePdfRoot, prune
 import { ZoteroConnector } from '../zotero/connector.js';
 import { normalizeWorkspace } from '../workspace.js';
 import { compareTasks } from './compare.js';
-import { filterPapers } from './filter.js';
+import { filterPapers, sortPapers } from './filter.js';
 import { TaskRunner } from './runner.js';
 import { computeStats } from './stats.js';
 import { applyAnnotations, countScreening, emptyState, normalizeGroups } from './states.js';
@@ -35,6 +35,10 @@ const PROBE_QUERY = 'machine learning';
 /** 已下载文件存在性检查的短缓存：详情轮询时不必反复 stat 同一批文件。 */
 const PDF_EXISTS_TTL_MS = 10_000;
 const pdfExistsCache = new Map();
+/** 右侧栏视图快照有效期：面板长时间不动时不拿旧页码替模型算「当前页」。 */
+const VIEW_TTL_MS = 30 * 60 * 1000;
+/** 最多保留多少个会话的视图快照，超出按上报时间淘汰最旧的。 */
+const MAX_VIEWS = 64;
 async function pdfFileExists(filePath) {
     const cached = pdfExistsCache.get(filePath);
     if (cached !== undefined && Date.now() - cached.at < PDF_EXISTS_TTL_MS)
@@ -79,6 +83,13 @@ export class TaskService {
     store = new TaskStore();
     events = new TaskEvents();
     runner = new TaskRunner();
+    /**
+     * 每个会话最近一次的右侧栏视图快照（内存、不落盘）。
+     *
+     * 模型工具跑在 Host 侧看不到界面，靠它把「当前页」「当前筛选全部」算准；
+     * 宿主重启即失效，与事件日志 rev 的生命周期一致。
+     */
+    views = new Map();
     /**
      * 全局「当前任务」：最后一次使用或打开的任务。
      *
@@ -195,7 +206,6 @@ export class TaskService {
                 tag: settings.zoteroTag,
             },
             storageDir: this.store.root,
-            version: PLUGIN_VERSION,
         };
     }
     async eventsSince(sinceRev) {
@@ -265,6 +275,53 @@ export class TaskService {
     focusTask(id, title, sessionId) {
         this.events.requestFocus(id, title, sessionId);
     }
+    /** 下发一条模型批量下载指令；右侧栏轮询 /events 拿增量后自行执行。 */
+    publishDownloadCommand(command) {
+        this.events.publishDownload(command);
+    }
+    /** 下发一条模型批量存入 Zotero 指令；与下载指令走独立的事件日志。 */
+    publishZoteroCommand(command) {
+        this.events.publishZotero(command);
+    }
+    /**
+     * 面板上报当前视图。会话 id 以请求头为准覆盖 body，防止伪造别的会话的视图；
+     * 时间也由 Host 重置，避免客户端时钟偏差影响过期判断。
+     */
+    saveViewSnapshot(sessionId, snapshot) {
+        if (sessionId === '' || snapshot.taskId === '')
+            return;
+        this.views.set(sessionId, { ...snapshot, sessionId, at: Date.now() });
+        if (this.views.size <= MAX_VIEWS)
+            return;
+        let oldestKey;
+        let oldestAt = Number.MAX_SAFE_INTEGER;
+        for (const [key, value] of this.views) {
+            if (value.at < oldestAt) {
+                oldestAt = value.at;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey !== undefined)
+            this.views.delete(oldestKey);
+    }
+    /** 取该会话在该任务上的最近视图；过期、跨任务或 rev 超前都视为不可信。 */
+    async getViewSnapshot(sessionId, taskId) {
+        await this.ready;
+        if (sessionId === undefined || sessionId === '')
+            return undefined;
+        const snapshot = this.views.get(sessionId);
+        if (snapshot === undefined || snapshot.taskId !== taskId)
+            return undefined;
+        if (Date.now() - snapshot.at > VIEW_TTL_MS) {
+            this.views.delete(sessionId);
+            return undefined;
+        }
+        // 每下载一篇都会让 rev +1，因此只做「快照不比任务更新」的宽松校验。
+        const task = await this.tryGet(taskId);
+        if (task === undefined || snapshot.rev > task.rev)
+            return undefined;
+        return snapshot;
+    }
     persistCurrent() {
         void this.store.saveCurrent({
             version: 1,
@@ -411,6 +468,10 @@ export class TaskService {
         // 模型工具导出到 <storage>/out/<taskId>/ 的文件随任务一起清掉。
         await rm(join(this.store.root, 'out', task.id), { recursive: true, force: true });
         this.events.remove(task.id);
+        for (const [key, value] of this.views) {
+            if (value.taskId === task.id)
+                this.views.delete(key);
+        }
         if (this.currentTaskId !== task.id)
             return;
         this.currentTaskId = undefined;
@@ -469,13 +530,7 @@ export class TaskService {
         const limit = clampInt(filter.limit ?? task.conditions.pageSize, 1, MAX_PAGE_LIMIT);
         const offset = clampInt(filter.offset ?? 0, 0, Number.MAX_SAFE_INTEGER);
         const papers = filterPapers(task, await this.withBaseFilter(task, filter));
-        const sort = filter.sort ?? task.conditions.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));
-        }
+        sortPapers(papers, filter.sort ?? task.conditions.sort);
         return {
             taskId: task.id,
             rev: task.rev,
@@ -689,13 +744,23 @@ export class TaskService {
             return { ok: false, error: error instanceof Error ? error.message : String(error) };
         }
     }
-    /** 把选中论文同步到 Zotero（含本地 PDF 附件）。 */
-    async zoteroSync(id, paperIds, workspace) {
+    /** 可写入的 Zotero 库与分类，供同步弹窗选择目标目录。 */
+    async zoteroTargets() {
+        const settings = getSettings();
+        try {
+            return await new ZoteroConnector(settings.zoteroBaseUrl).listTargets();
+        }
+        catch (error) {
+            return { ok: false, targets: [], error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /** 把选中论文同步到 Zotero（含本地 PDF 附件），并记录每篇的同步状态。 */
+    async zoteroSync(id, paperIds, workspace, target) {
         const settings = getSettings();
         if (!settings.zoteroEnabled)
             throw new SearchError('bad_request', 'Zotero 同步已在设置中关闭');
         const task = await this.get(id);
-        const target = normalizeWorkspace(workspace) ?? normalizeWorkspace(task.workspace);
+        const workspaceDir = normalizeWorkspace(workspace) ?? normalizeWorkspace(task.workspace);
         const wanted = paperIds === undefined || paperIds.length === 0
             ? task.result.papers.slice(0, 50)
             : paperIds.map((paperId) => findPaper(task, paperId));
@@ -706,7 +771,9 @@ export class TaskService {
         if (!probe.ok) {
             throw new SearchError('network_error', `Zotero 未运行或 connector 不可达：${probe.error ?? settings.zoteroBaseUrl}`);
         }
-        const readOnlyAttachments = settings.zoteroAttachPdf && probe.collection?.filesEditable === false;
+        // 目标目录优先：用户选定的分类可能是另一个库，不能只看当前选中的分类。
+        const filesEditable = target?.filesEditable ?? probe.collection?.filesEditable;
+        const readOnlyAttachments = settings.zoteroAttachPdf && filesEditable === false;
         const attachPdf = settings.zoteroAttachPdf && !readOnlyAttachments;
         const inputs = [];
         for (const paper of wanted) {
@@ -715,7 +782,7 @@ export class TaskService {
             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)
+                ? await this.ensureLocalPdf(paper, workspaceDir, state?.pdfFile)
                 : undefined;
             inputs.push({ paper, tags, ...(pdfPath === undefined ? {} : { pdfPath }) });
         }
@@ -724,12 +791,31 @@ export class TaskService {
                 baseUrl: settings.zoteroBaseUrl,
                 attachPdf,
                 tag: settings.zoteroTag,
+                ...(target === undefined
+                    ? {}
+                    : {
+                        targetId: target.id,
+                        ...(target.name === undefined ? {} : { targetName: target.name }),
+                    }),
             });
-            if (probe.collection === undefined) {
+            if (target === undefined && probe.collection === undefined) {
                 result.messages.unshift('Zotero 当前未选择分类，条目已保存到「我的文库」');
             }
             else if (readOnlyAttachments) {
-                result.messages.unshift('当前分类不可写附件，已只保存条目；可在 Zotero 中换一个可写分类后重试');
+                const label = target === undefined ? '当前分类' : `「${target.name ?? target.id}」`;
+                result.messages.unshift(`${label}不可写附件，已只保存条目；可换一个可写目录后重试`);
+            }
+            const collectionName = target === undefined ? probe.collection?.name : target.name;
+            for (const item of result.items) {
+                await this.setZoteroState(task, item.paperId, item.ok
+                    ? {
+                        zoteroStatus: 'synced',
+                        ...(collectionName === undefined ? {} : { zoteroCollection: collectionName }),
+                    }
+                    : {
+                        zoteroStatus: 'failed',
+                        zoteroError: item.error ?? result.messages[0] ?? '同步失败',
+                    });
             }
             return result;
         }
@@ -737,6 +823,26 @@ export class TaskService {
             throw new SearchError('upstream_error', error instanceof Error ? error.message : String(error));
         }
     }
+    /** 记录单篇文献的 Zotero 同步状态；与 PDF 状态一样写回任务并广播。 */
+    async setZoteroState(task, paperId, patch) {
+        if (this.store.summary(task.id) === undefined)
+            return;
+        const current = task.states[paperId] ?? emptyState();
+        const next = { ...current, zoteroStatus: patch.zoteroStatus };
+        if (patch.zoteroCollection === undefined)
+            delete next.zoteroCollection;
+        else
+            next.zoteroCollection = patch.zoteroCollection.slice(0, 200);
+        if (patch.zoteroError === undefined)
+            delete next.zoteroError;
+        else
+            next.zoteroError = patch.zoteroError.slice(0, 300);
+        task.states[paperId] = next;
+        task.rev += 1;
+        task.updatedAt = new Date().toISOString();
+        await this.store.save(task);
+        this.events.publish(toSummary(task));
+    }
     /** 下载目录可写性测试（设置页）。 */
     async storageProbe(workspace) {
         const outcome = await probePdfRoot(workspace);
@@ -840,6 +946,13 @@ export class TaskService {
             return undefined;
         return { paperIds: new Set(base.result.papers.map((paper) => paper.paperId)), rev: base.rev };
     }
+    /**
+     * 供模型下载工具复用：`newOnly` 需要基准任务的论文集合才能与界面口径一致。
+     * 直接暴露给工具层，避免下载范围解析和 `/results` 出现两套过滤逻辑。
+     */
+    async resolveDownloadFilter(id, filter) {
+        return this.withBaseFilter(await this.get(id), filter);
+    }
     /** `newOnly` 需要基准任务的论文集合；基准已删除时忽略该条件。 */
     async withBaseFilter(task, filter) {
         if (filter.newOnly !== true || task.fromTaskId === undefined)

package/lib/host/tools.d.ts

@@ -9,6 +9,10 @@
  * - `literature_task`：读取/修改已保存任务（含轮次历史），写入筛读与分组，
  *   做新老对比与统计。
  * - `literature_export`：把任务（按筛选）导出为 CSV / RIS / BibTeX / Markdown 并落盘。
+ * - `literature_download`：把自然语言下载请求解析成已校验的 paperId 清单，
+ *   通过事件下发给右侧栏，由右侧栏复用批量下载弹窗执行并逐篇展示。
+ * - `literature_zotero`：与下载共用范围解析，改为让右侧栏复用 Zotero 同步
+ *   弹窗；对话里点名目录且匹配成功才自动开跑，否则由用户选目录。
  *
  * 参数在边界做一次校验（模型输出不可信），服务层仍会再兜底。
  */