dsh-plugin-litsearch 0.2.0 → 0.3.0

package/lib/host/paths.d.ts

@@ -9,8 +9,9 @@
  * - 不覆盖新目录里已有的文件，重复启动不会反复迁移；
  * - 复制失败或校验不通过时回退到旧目录读取，保证任务标注不丢。
  *
- * PDF 的可读文件由设置项 `pdfRoot` 决定（默认 `~/Downloads/dsh-litsearch`），
- * 不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs` 随数据目录一起搬迁。
+ * PDF 的可读文件由设置项 `pdfRoot` 决定（默认落在当前会话工作目录下的
+ * `dsh-litsearch/`），不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs`
+ * 随数据目录一起搬迁。
  */
 export declare const PLUGIN_ID = "dsh-plugin-litsearch";
 /** 历史版本使用的目录名（`$DSH_HOME` 下的一级目录）。 */

package/lib/host/paths.js

@@ -9,8 +9,9 @@
  * - 不覆盖新目录里已有的文件，重复启动不会反复迁移；
  * - 复制失败或校验不通过时回退到旧目录读取，保证任务标注不丢。
  *
- * PDF 的可读文件由设置项 `pdfRoot` 决定（默认 `~/Downloads/dsh-litsearch`），
- * 不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs` 随数据目录一起搬迁。
+ * PDF 的可读文件由设置项 `pdfRoot` 决定（默认落在当前会话工作目录下的
+ * `dsh-litsearch/`），不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs`
+ * 随数据目录一起搬迁。
  */
 import { copyFile, mkdir, readdir, rm, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';

package/lib/host/pdf/root.d.ts

@@ -0,0 +1,11 @@
+/**
+ * PDF 下载目录的纯路径计算。
+ *
+ * 优先级：显式配置 `pdfRoot` → 会话工作目录下的 `dsh-litsearch/` →
+ * 历史默认 `~/Downloads/dsh-litsearch`。保持无相对导入，便于单测直接加载。
+ */
+/** 工作目录（或 Downloads）下的固定子目录名。 */
+export declare const PDF_SUBDIR = "dsh-litsearch";
+/** 展开 `~` / `~/...`；其它路径原样返回。 */
+export declare function expandHomePath(path: string, home?: string): string;
+export declare function resolvePdfRootPath(configured: string, workspace: string | undefined, home?: string): string;

package/lib/host/pdf/root.js

@@ -0,0 +1,27 @@
+/**
+ * PDF 下载目录的纯路径计算。
+ *
+ * 优先级：显式配置 `pdfRoot` → 会话工作目录下的 `dsh-litsearch/` →
+ * 历史默认 `~/Downloads/dsh-litsearch`。保持无相对导入，便于单测直接加载。
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** 工作目录（或 Downloads）下的固定子目录名。 */
+export const PDF_SUBDIR = 'dsh-litsearch';
+/** 展开 `~` / `~/...`；其它路径原样返回。 */
+export function expandHomePath(path, home = homedir()) {
+    if (path === '~')
+        return home;
+    if (path.startsWith('~/'))
+        return join(home, path.slice(2));
+    return path;
+}
+export function resolvePdfRootPath(configured, workspace, home = homedir()) {
+    const custom = configured.trim();
+    if (custom !== '')
+        return expandHomePath(custom, home);
+    const base = workspace?.trim() ?? '';
+    if (base !== '')
+        return join(base, PDF_SUBDIR);
+    return join(home, 'Downloads', PDF_SUBDIR);
+}

package/lib/host/pdf/store.d.ts

@@ -18,8 +18,8 @@ export interface PdfResolution {
     url?: string;
     error?: string;
 }
-/** 设置里的根目录；空串回落到 ~/Downloads/dsh-litsearch。 */
-export declare function resolvePdfRoot(): string;
+/** 设置里的根目录；未配置时落在会话工作目录下的 dsh-litsearch/。 */
+export declare function resolvePdfRoot(workspace?: string): string;
 export declare function pdfCacheDir(storageRoot: string): string;
 /** 尝试所有候选并返回第一个合法 PDF；失败时给出可展示的状态与原因。 */
 export declare function resolvePdf(paper: Paper, signal?: AbortSignal): Promise<PdfResolution>;
@@ -31,7 +31,7 @@ export interface FetchPdfOptions {
 /** 下载并校验单个 PDF；内部处理重定向，每一步都重新校验目标地址。 */
 export declare function fetchPdf(url: string, options?: FetchPdfOptions): Promise<Buffer>;
 /** 写入去重缓存与用户目录；返回两份路径。 */
-export declare function persistPdf(buffer: Buffer, storageRoot: string, paper: Paper): Promise<{
+export declare function persistPdf(buffer: Buffer, storageRoot: string, paper: Paper, workspace?: string): Promise<{
     cachePath: string;
     filePath: string;
     filename: string;
@@ -41,14 +41,22 @@ 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): Promise<Buffer | null>;
+export declare function readLocalPdf(paper: Paper, workspace?: string): Promise<Buffer | null>;
 /** 清理 PDF 缓存目录。 */
 export declare function cleanupPdfCache(storageRoot: string): Promise<{
     removed: number;
     freedBytes: number;
 }>;
+/**
+ * 按总量上限修剪去重缓存：超出时从最旧（mtime）开始删，直到不超过上限。
+ * `maxBytes <= 0` 表示关闭自动清理。
+ */
+export declare function prunePdfCache(storageRoot: string, maxBytes: number): Promise<{
+    removed: number;
+    freedBytes: number;
+}>;
 /** 测试下载目录是否可写（设置页）。 */
-export declare function probePdfRoot(): Promise<{
+export declare function probePdfRoot(workspace?: string): Promise<{
     root: string;
     writable: boolean;
     error?: string;

package/lib/host/pdf/store.js

@@ -7,11 +7,11 @@
 import { createHash } from 'node:crypto';
 import { lookup } from 'node:dns/promises';
 import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
 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 { resolvePdfRootPath } from './root.js';
 const MAX_REDIRECTS = 5;
 const FETCH_TIMEOUT_MS = 20_000;
 const MAX_PDF_BYTES_DEFAULT = 30 * 1024 * 1024;
@@ -26,16 +26,9 @@ export class PdfFetchError extends Error {
             this.status = status;
     }
 }
-/** 设置里的根目录；空串回落到 ~/Downloads/dsh-litsearch。 */
-export function resolvePdfRoot() {
-    const configured = getSettings().pdfRoot.trim();
-    if (configured === '')
-        return join(homedir(), 'Downloads', 'dsh-litsearch');
-    if (configured === '~')
-        return homedir();
-    if (configured.startsWith('~/'))
-        return join(homedir(), configured.slice(2));
-    return configured;
+/** 设置里的根目录；未配置时落在会话工作目录下的 dsh-litsearch/。 */
+export function resolvePdfRoot(workspace) {
+    return resolvePdfRootPath(getSettings().pdfRoot, workspace);
 }
 export function pdfCacheDir(storageRoot) {
     return join(storageRoot, 'pdfs');
@@ -138,13 +131,13 @@ export async function fetchPdf(url, options = {}) {
     throw new PdfFetchError('failed', `重定向超过 ${MAX_REDIRECTS} 次`);
 }
 /** 写入去重缓存与用户目录；返回两份路径。 */
-export async function persistPdf(buffer, storageRoot, paper) {
+export async function persistPdf(buffer, storageRoot, paper, workspace) {
     const hash = createHash('sha256').update(buffer).digest('hex');
     const cacheDir = pdfCacheDir(storageRoot);
     await mkdir(cacheDir, { recursive: true });
     const cachePath = join(cacheDir, `${hash}.pdf`);
     await writeFile(cachePath, buffer);
-    const root = resolvePdfRoot();
+    const root = resolvePdfRoot(workspace);
     await mkdir(root, { recursive: true });
     const filename = readableFilename(paper);
     const filePath = join(root, filename);
@@ -178,8 +171,8 @@ export function readableFilename(paper) {
     return `${base.slice(0, 120)}.pdf`;
 }
 /** 预览时读取已保存的可读文件；没有则返回 null（由调用方决定是否联网）。 */
-export async function readLocalPdf(paper) {
-    return readSavedPdf(join(resolvePdfRoot(), readableFilename(paper)));
+export async function readLocalPdf(paper, workspace) {
+    return readSavedPdf(join(resolvePdfRoot(workspace), readableFilename(paper)));
 }
 /** 清理 PDF 缓存目录。 */
 export async function cleanupPdfCache(storageRoot) {
@@ -206,9 +199,61 @@ export async function cleanupPdfCache(storageRoot) {
     }
     return { removed, freedBytes };
 }
+/**
+ * 按总量上限修剪去重缓存：超出时从最旧（mtime）开始删，直到不超过上限。
+ * `maxBytes <= 0` 表示关闭自动清理。
+ */
+export async function prunePdfCache(storageRoot, maxBytes) {
+    if (!Number.isFinite(maxBytes) || maxBytes <= 0)
+        return { removed: 0, freedBytes: 0 };
+    const dir = pdfCacheDir(storageRoot);
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return { removed: 0, freedBytes: 0 };
+    }
+    const files = [];
+    let total = 0;
+    for (const name of names) {
+        if (!name.endsWith('.pdf'))
+            continue;
+        const path = join(dir, name);
+        try {
+            const info = await stat(path);
+            if (!info.isFile())
+                continue;
+            files.push({ path, size: info.size, mtimeMs: info.mtimeMs });
+            total += info.size;
+        }
+        catch {
+            // 单个缓存文件读不到元信息时跳过，不影响修剪其余文件。
+        }
+    }
+    if (total <= maxBytes)
+        return { removed: 0, freedBytes: 0 };
+    files.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    let removed = 0;
+    let freedBytes = 0;
+    for (const file of files) {
+        if (total <= maxBytes)
+            break;
+        try {
+            await rm(file.path, { force: true });
+            total -= file.size;
+            freedBytes += file.size;
+            removed += 1;
+        }
+        catch {
+            // 删除失败继续尝试更近的文件。
+        }
+    }
+    return { removed, freedBytes };
+}
 /** 测试下载目录是否可写（设置页）。 */
-export async function probePdfRoot() {
-    const root = resolvePdfRoot();
+export async function probePdfRoot(workspace) {
+    const root = resolvePdfRoot(workspace);
     const probe = join(root, `.write-test-${process.pid}-${Date.now()}`);
     try {
         await mkdir(root, { recursive: true });

package/lib/host/router.js

@@ -6,13 +6,15 @@
  * `sec-fetch-site: cross-site`。写端点额外要求自定义头 + JSON content-type，
  * 两者一起让浏览器必须预检，堵掉跨站表单与简单请求。
  */
-import { MAX_LIMIT, ROUTE_PREFIX, WRITE_HEADER } from '../search/config.js';
+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 { resolveSessionWorkspace } from './workspace.js';
 const MAX_BODY_BYTES = 1_000_000;
 const SORT_MODES = ['relevance', 'citations', 'year'];
-const LANGUAGES = ['any', 'eng', 'chi'];
+const LANGUAGES = TASK_LANGUAGES;
 const ORIGINS = ['model', 'panel', 'history', 'api'];
 const SCREENINGS = ['unread', 'read', 'included', 'excluded'];
 const PDF_STATUSES = [
@@ -39,6 +41,13 @@ function isTrusted(req) {
         return false;
     return isLoopbackHost(req.headers.host);
 }
+/** 面板把当前会话 id 放在请求头里；iframe 预览等无法带头部的 GET 用查询参数。 */
+function readSessionId(req, params) {
+    const header = req.headers[SESSION_HEADER];
+    const raw = typeof header === 'string' && header.trim() !== '' ? header : params.get('session') ?? '';
+    const id = raw.trim();
+    return id === '' ? undefined : id;
+}
 /** 写端点要求自定义头 + JSON：跨站请求无法在不触发预检的情况下伪造。 */
 function hasWriteIntent(req) {
     if (req.headers[WRITE_HEADER] !== '1')
@@ -561,7 +570,7 @@ function parseSegments(pathname) {
         }
     });
 }
-async function handleTasks(service, req, res, seg, params) {
+async function handleTasks(service, req, res, seg, params, sessionId) {
     const id = seg[1];
     if (id === undefined) {
         if (req.method === 'GET') {
@@ -570,7 +579,8 @@ async function handleTasks(service, req, res, seg, params) {
         }
         if (req.method === 'POST') {
             const input = readCreateInput(await readJsonBody(req));
-            const task = await service.create({ ...input, origin: 'panel' });
+            const workspace = await resolveSessionWorkspace(sessionId);
+            const task = await service.create({ ...input, origin: 'panel', workspace });
             ok(res, await service.getDetail(task.id), 201);
             return;
         }
@@ -629,7 +639,7 @@ async function handleTasks(service, req, res, seg, params) {
             fail(res, 405, 'bad_request', 'activate 仅支持 POST');
             return;
         }
-        const task = await service.activate(id);
+        const task = await service.activate(id, await resolveSessionWorkspace(sessionId));
         ok(res, await service.getDetail(task.id));
         return;
     }
@@ -670,7 +680,7 @@ async function handleTasks(service, req, res, seg, params) {
                 fail(res, 405, 'bad_request', 'download 仅支持 POST');
                 return;
             }
-            ok(res, await service.downloadPdf(id, paperId));
+            ok(res, await service.downloadPdf(id, paperId, await resolveSessionWorkspace(sessionId)));
             return;
         }
         if (op === 'pdf') {
@@ -679,7 +689,7 @@ async function handleTasks(service, req, res, seg, params) {
                 return;
             }
             try {
-                const file = await service.previewPdf(id, paperId);
+                const file = await service.previewPdf(id, paperId, await resolveSessionWorkspace(sessionId));
                 sendPdf(req, res, file.buffer, file.filename);
             }
             catch (error) {
@@ -711,7 +721,7 @@ async function handleTasks(service, req, res, seg, params) {
         }
         const body = await readJsonBody(req);
         const ids = readStringArray(body['paperIds'], 'paperIds', 50, 80);
-        ok(res, await service.zoteroSync(id, ids === undefined || ids === null ? undefined : ids));
+        ok(res, await service.zoteroSync(id, ids === undefined || ids === null ? undefined : ids, await resolveSessionWorkspace(sessionId)));
         return;
     }
     if (action === 'compare') {
@@ -737,7 +747,8 @@ async function handleTasks(service, req, res, seg, params) {
             throw new SearchError('conflict', '任务正在运行');
         // 面板里主动重跑 = 用户正在这个任务里工作，把它设为「当前任务」。
         service.setCurrentTask(id);
-        void service.run(id, mode, 'panel').catch((error) => {
+        const workspace = await resolveSessionWorkspace(sessionId);
+        void service.run(id, mode, 'panel', workspace).catch((error) => {
             console.warn('[dsh-plugin-litsearch] 任务执行失败：', error);
         });
         ok(res, await service.getDetail(id), 202);
@@ -810,14 +821,15 @@ export function createHandler(service) {
                     return;
                 }
                 if (seg[1] === 'storage' && req.method === 'POST') {
-                    ok(res, await service.storageProbe());
+                    const workspace = await resolveSessionWorkspace(readSessionId(req, url.searchParams));
+                    ok(res, await service.storageProbe(workspace));
                     return;
                 }
                 fail(res, 404, 'not_found', `未知设置端点 ${seg[1] ?? ''}`);
                 return;
             }
             if (head === 'tasks') {
-                await handleTasks(service, req, res, seg, url.searchParams);
+                await handleTasks(service, req, res, seg, url.searchParams, readSessionId(req, url.searchParams));
                 return;
             }
             if (head === 'export') {

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

@@ -37,6 +37,8 @@ export declare function filterPapers(task: SearchTask, filter?: PaperFilter): Pa
 export declare function screeningOf(task: SearchTask, paper: Paper): Screening;
 /** 有效全文状态：没有人工/下载记录时，上游给的 PDF 直链视为可用。 */
 export declare function pdfStatusOf(task: SearchTask, paper: Paper): PdfStatus;
-export declare function matchesLanguage(paper: Paper, language: TaskLanguage): boolean;
+export declare function matchesLanguage(paper: {
+    language?: string;
+}, language: TaskLanguage): boolean;
 /** 稳定的筛选指纹（统计缓存 key 的一部分）。 */
 export declare function filterKey(filter: PaperFilter): string;

package/lib/host/tasks/filter.js

@@ -72,11 +72,52 @@ export function pdfStatusOf(task, paper) {
 export function matchesLanguage(paper, language) {
     if (language === 'any')
         return true;
-    const value = (paper.language ?? '').toLowerCase();
-    if (language === 'chi')
-        return value.startsWith('chi') || value.startsWith('zh');
-    return value.startsWith('eng') || value.startsWith('en');
+    const raw = (paper.language ?? '').trim().toLowerCase();
+    // 兼容 `en-US` / `zh-CN` 这类带地区的写法，只取主语言码。
+    const code = LANGUAGE_ALIASES[raw] ?? LANGUAGE_ALIASES[raw.split(/[-_]/u)[0] ?? ''];
+    return code !== undefined && code === language;
 }
+/**
+ * 上游语言标记 → 统一的 PubMed 三字母码。
+ *
+ * PubMed / Europe PMC 给三字母码，OpenAlex 等给两字母码，这里都收敛到同一套，
+ * 避免语言筛选把同一种语言判成两种。
+ */
+const LANGUAGE_ALIASES = {
+    eng: 'eng',
+    en: 'eng',
+    english: 'eng',
+    chi: 'chi',
+    zho: 'chi',
+    zh: 'chi',
+    chinese: 'chi',
+    jpn: 'jpn',
+    ja: 'jpn',
+    japanese: 'jpn',
+    kor: 'kor',
+    ko: 'kor',
+    korean: 'kor',
+    fre: 'fre',
+    fra: 'fre',
+    fr: 'fre',
+    french: 'fre',
+    ger: 'ger',
+    deu: 'ger',
+    de: 'ger',
+    german: 'ger',
+    spa: 'spa',
+    es: 'spa',
+    spanish: 'spa',
+    rus: 'rus',
+    ru: 'rus',
+    russian: 'rus',
+    ita: 'ita',
+    it: 'ita',
+    italian: 'ita',
+    por: 'por',
+    pt: 'por',
+    portuguese: 'por',
+};
 /** 稳定的筛选指纹（统计缓存 key 的一部分）。 */
 export function filterKey(filter) {
     return [

package/lib/host/tasks/runner.js

@@ -8,6 +8,7 @@
 import { DEFAULT_TASK_MAX_ROUNDS, MAX_LIMIT, getSettings } from '../../search/config.js';
 import { searchSources } from '../../search/aggregate.js';
 import { mergeHits } from '../../search/identity.js';
+import { matchesLanguage } from './filter.js';
 import { finishRound, startRound } from './rounds.js';
 import { countScreening } from './states.js';
 class RunCanceled extends Error {
@@ -198,11 +199,3 @@ function matchesConditions(paper, conditions) {
     }
     return true;
 }
-function matchesLanguage(paper, language) {
-    if (language === 'any')
-        return true;
-    const value = (paper.language ?? '').toLowerCase();
-    if (language === 'chi')
-        return value.startsWith('chi') || value.startsWith('zh');
-    return value.startsWith('eng') || value.startsWith('en');
-}

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

@@ -26,6 +26,8 @@ export interface CreateTaskInput {
     sort?: SortMode;
     origin: TaskOrigin;
     fromTaskId?: string;
+    /** 发起方所在会话的工作目录；下载默认落在这里。 */
+    workspace?: string;
     runNow?: boolean;
 }
 export interface TaskPatch {
@@ -76,6 +78,8 @@ export declare class TaskService {
      * 又新建一个同名任务。
      */
     private restore;
+    /** 按设置的总量上限修剪 PDF 去重缓存；失败只告警，不阻断启动。 */
+    private trimPdfCache;
     /** 没有可用快照时，把最近更新的任务设为当前任务并落盘。 */
     private bootstrapCurrentTask;
     get globalRev(): number;
@@ -101,7 +105,9 @@ export declare class TaskService {
     focusTask(id: string, title: string, sessionId?: string): void;
     private persistCurrent;
     /** 用户从任务列表点开某任务 = 进入该任务，之后的模型检索默认落在这里。 */
-    activate(id: string): Promise<SearchTask>;
+    activate(id: string, workspace?: string): Promise<SearchTask>;
+    /** 记下任务最近一次所在的工作目录；只改变下载落点，不改变 rev。 */
+    private applyWorkspace;
     /** 等待该任务当前这一轮结束；返回是否确实已空闲。 */
     waitUntilIdle(id: string, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
     create(input: CreateTaskInput): Promise<SearchTask>;
@@ -112,7 +118,7 @@ export declare class TaskService {
      *
      * 任务已缓存时同步登记运行态，调用方紧接着调 `waitUntilIdle` 也不会误判为空闲。
      */
-    run(id: string, mode?: 'new' | 'more', origin?: TaskOrigin): Promise<SearchTask>;
+    run(id: string, mode?: 'new' | 'more', origin?: TaskOrigin, workspace?: string): Promise<SearchTask>;
     /**
      * 在同一任务内开新一轮：全量替换检索条件后执行，**不新建任务、不新开 tab**。
      *
@@ -137,9 +143,9 @@ export declare class TaskService {
     /** 设置页清理：任务文件与 PDF 缓存。 */
     cleanup(scope: CleanupScope): Promise<CleanupResult>;
     /** 下载单篇 PDF；失败时写入失败状态，若有 EPMC 全文则降级为 html-only。 */
-    downloadPdf(id: string, paperId: string): Promise<PdfDownloadResult>;
+    downloadPdf(id: string, paperId: string, workspace?: string): Promise<PdfDownloadResult>;
     /** PDF 预览：优先用已落地文件；没有则临时抓取一次但不落盘。 */
-    previewPdf(id: string, paperId: string): Promise<{
+    previewPdf(id: string, paperId: string, workspace?: string): Promise<{
         buffer: Buffer;
         filename: string;
     }>;
@@ -152,9 +158,9 @@ export declare class TaskService {
     /** 测试 Zotero connector 是否可达，并返回当前选中的分类。 */
     zoteroProbe(): Promise<ZoteroProbeResult>;
     /** 把选中论文同步到 Zotero（含本地 PDF 附件）。 */
-    zoteroSync(id: string, paperIds?: readonly string[]): Promise<ZoteroSyncResult>;
+    zoteroSync(id: string, paperIds?: readonly string[], workspace?: string): Promise<ZoteroSyncResult>;
     /** 下载目录可写性测试（设置页）。 */
-    storageProbe(): Promise<StorageProbeResult>;
+    storageProbe(workspace?: string): Promise<StorageProbeResult>;
     private ensureLocalPdf;
     private setPdfState;
     /** 单源诊断：用固定短查询测一次连通性与延迟（不受冷却影响）。 */