dsh-plugin-litsearch 0.1.0 → 0.3.0

package/lib/host/events.d.ts

@@ -9,8 +9,11 @@ import type { EventsPage, TaskSummary } from '../search/types.js';
 export declare class TaskEvents {
     private rev;
     private readonly entries;
+    private focus;
     get currentRev(): number;
     publish(summary: TaskSummary): void;
+    /** 请求客户端把某个任务 tab 打开/切到前台（面板关着时重新打开）。 */
+    requestFocus(taskId: string, title: string, sessionId?: string): void;
     remove(id: string): void;
     since(sinceRev: number): EventsPage;
 }

package/lib/host/events.js

@@ -8,6 +8,7 @@
 export class TaskEvents {
     rev = 0;
     entries = new Map();
+    focus;
     get currentRev() {
         return this.rev;
     }
@@ -15,8 +16,21 @@ export class TaskEvents {
         this.rev += 1;
         this.entries.set(summary.id, { globalRev: this.rev, summary });
     }
+    /** 请求客户端把某个任务 tab 打开/切到前台（面板关着时重新打开）。 */
+    requestFocus(taskId, title, sessionId) {
+        this.rev += 1;
+        this.focus = {
+            globalRev: this.rev,
+            taskId,
+            title,
+            at: Date.now(),
+            ...(sessionId === undefined ? {} : { sessionId }),
+        };
+    }
     remove(id) {
         this.entries.delete(id);
+        if (this.focus?.taskId === id)
+            this.focus = undefined;
     }
     since(sinceRev) {
         if (!Number.isFinite(sinceRev) || sinceRev < 0) {
@@ -29,6 +43,16 @@ export class TaskEvents {
             .filter((entry) => entry.globalRev > sinceRev)
             .sort((a, b) => a.globalRev - b.globalRev)
             .map((entry) => entry.summary);
-        return { rev: this.rev, reset: false, tasks };
+        const focus = this.focus !== undefined && this.focus.globalRev > sinceRev
+            ? {
+                taskId: this.focus.taskId,
+                title: this.focus.title,
+                at: this.focus.at,
+                ...(this.focus.sessionId === undefined
+                    ? {}
+                    : { sessionId: this.focus.sessionId }),
+            }
+            : undefined;
+        return { rev: this.rev, reset: false, tasks, ...(focus === undefined ? {} : { focus }) };
     }
 }

package/lib/host/paths.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 插件数据目录解析与旧版数据迁移。
+ *
+ * 平台约定：插件私有数据统一放在 `$DSH_HOME/storages/<plugin-id>/`，
+ * `DSH_HOME` 由宿主注入，未设置时回落 `~/.dsh`。本插件历史版本把数据直接
+ * 写在 `~/.dsh/dsh-litsearch/`，这里负责一次性搬迁到统一存储区：
+ *
+ * - 只复制、不删除，旧目录原样保留作备份；
+ * - 不覆盖新目录里已有的文件，重复启动不会反复迁移；
+ * - 复制失败或校验不通过时回退到旧目录读取，保证任务标注不丢。
+ *
+ * PDF 的可读文件由设置项 `pdfRoot` 决定（默认落在当前会话工作目录下的
+ * `dsh-litsearch/`），不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs`
+ * 随数据目录一起搬迁。
+ */
+export declare const PLUGIN_ID = "dsh-plugin-litsearch";
+/** 历史版本使用的目录名（`$DSH_HOME` 下的一级目录）。 */
+export declare const LEGACY_DIR = "dsh-litsearch";
+/** 解析宿主数据根目录；支持绝对路径、`~/...` 与空值回落。 */
+export declare function dshHome(env?: NodeJS.ProcessEnv, home?: string): string;
+/** 当前数据根目录：平台统一存储区下的插件域。 */
+export declare function storageRoot(env?: NodeJS.ProcessEnv, home?: string): string;
+/** 旧数据根目录候选，按优先级排列，已排除新根目录。 */
+export declare function legacyRoots(env?: NodeJS.ProcessEnv, home?: string): string[];
+/** 目录里是否存在至少一个任务正文文件（索引与快照不算）。 */
+export declare function hasTaskFiles(root: string): Promise<boolean>;
+export interface StorageResolution {
+    /** 最终使用的数据根目录。 */
+    root: string;
+    /** 本次复制的文件数。 */
+    copied: number;
+    /** 从该旧目录迁移成功。 */
+    migratedFrom?: string;
+    /** 迁移失败，暂时回退到该旧目录读取。 */
+    fallbackFrom?: string;
+}
+/**
+ * 决定最终数据根目录，并在必要时做一次性迁移：
+ *
+ * 1. 新目录已有任务 → 直接使用，绝不碰旧数据；
+ * 2. 新目录为空且旧目录有任务 → 复制缺失文件到新目录，旧目录保留；
+ * 3. 复制失败或复制后仍无任务 → 回滚本次副本并回退到旧目录读取。
+ */
+export declare function resolveStorageRoot(env?: NodeJS.ProcessEnv, home?: string): Promise<StorageResolution>;

package/lib/host/paths.js

@@ -0,0 +1,129 @@
+/**
+ * 插件数据目录解析与旧版数据迁移。
+ *
+ * 平台约定：插件私有数据统一放在 `$DSH_HOME/storages/<plugin-id>/`，
+ * `DSH_HOME` 由宿主注入，未设置时回落 `~/.dsh`。本插件历史版本把数据直接
+ * 写在 `~/.dsh/dsh-litsearch/`，这里负责一次性搬迁到统一存储区：
+ *
+ * - 只复制、不删除，旧目录原样保留作备份；
+ * - 不覆盖新目录里已有的文件，重复启动不会反复迁移；
+ * - 复制失败或校验不通过时回退到旧目录读取，保证任务标注不丢。
+ *
+ * PDF 的可读文件由设置项 `pdfRoot` 决定（默认落在当前会话工作目录下的
+ * `dsh-litsearch/`），不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs`
+ * 随数据目录一起搬迁。
+ */
+import { copyFile, mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+export const PLUGIN_ID = 'dsh-plugin-litsearch';
+/** 历史版本使用的目录名（`$DSH_HOME` 下的一级目录）。 */
+export const LEGACY_DIR = 'dsh-litsearch';
+/** 允许搬迁的条目：任务正文与索引、导出文件、PDF 去重缓存、当前任务快照。 */
+const MIGRATABLE_ENTRIES = ['tasks', 'out', 'pdfs', 'current.json'];
+/** 解析宿主数据根目录；支持绝对路径、`~/...` 与空值回落。 */
+export function dshHome(env = process.env, home = homedir()) {
+    const raw = env.DSH_HOME?.trim() ?? '';
+    if (raw === '')
+        return join(home, '.dsh');
+    if (raw === '~')
+        return home;
+    if (raw.startsWith('~/'))
+        return join(home, raw.slice(2));
+    // 绝对路径原样规范化，相对路径按进程工作目录解析（与宿主 path.resolve 一致）。
+    return resolve(raw);
+}
+/** 当前数据根目录：平台统一存储区下的插件域。 */
+export function storageRoot(env = process.env, home = homedir()) {
+    return join(dshHome(env, home), 'storages', PLUGIN_ID);
+}
+/** 旧数据根目录候选，按优先级排列，已排除新根目录。 */
+export function legacyRoots(env = process.env, home = homedir()) {
+    const current = storageRoot(env, home);
+    const candidates = [
+        join(dshHome(env, home), LEGACY_DIR), // 过渡形态：$DSH_HOME/dsh-litsearch
+        join(home, '.dsh', LEGACY_DIR), // 历史硬编码：~/.dsh/dsh-litsearch
+    ];
+    return [...new Set(candidates)].filter((path) => path !== current);
+}
+/** 目录里是否存在至少一个任务正文文件（索引与快照不算）。 */
+export async function hasTaskFiles(root) {
+    const names = await readdir(join(root, 'tasks')).catch(() => []);
+    return names.some((name) => name.endsWith('.json') && name !== 'index.json');
+}
+/**
+ * 决定最终数据根目录，并在必要时做一次性迁移：
+ *
+ * 1. 新目录已有任务 → 直接使用，绝不碰旧数据；
+ * 2. 新目录为空且旧目录有任务 → 复制缺失文件到新目录，旧目录保留；
+ * 3. 复制失败或复制后仍无任务 → 回滚本次副本并回退到旧目录读取。
+ */
+export async function resolveStorageRoot(env = process.env, home = homedir()) {
+    const root = storageRoot(env, home);
+    if (await hasTaskFiles(root))
+        return { root, copied: 0 };
+    for (const legacy of legacyRoots(env, home)) {
+        if (!(await hasTaskFiles(legacy)))
+            continue;
+        const copied = [];
+        try {
+            await copyLegacyStorage(legacy, root, copied);
+            if (await hasTaskFiles(root)) {
+                console.info(`[dsh-plugin-litsearch] 任务数据已迁移：${legacy} → ${root}（${copied.length} 个文件，原目录保留）`);
+                return { root, migratedFrom: legacy, copied: copied.length };
+            }
+            await rollback(copied);
+        }
+        catch (error) {
+            await rollback(copied);
+            console.warn('[dsh-plugin-litsearch] 任务数据迁移失败：', error);
+        }
+        console.warn(`[dsh-plugin-litsearch] 暂时沿用旧任务目录：${legacy}`);
+        return { root: legacy, fallbackFrom: legacy, copied: 0 };
+    }
+    return { root, copied: 0 };
+}
+/** 复制旧目录里的已知条目；目标已存在则跳过，复制路径写入 `copied` 供回滚。 */
+async function copyLegacyStorage(from, to, copied) {
+    for (const entry of MIGRATABLE_ENTRIES) {
+        const source = join(from, entry);
+        const target = join(to, entry);
+        const info = await stat(source).catch(() => null);
+        if (info === null)
+            continue;
+        if (info.isFile()) {
+            await copyFileIfAbsent(source, target, copied);
+        }
+        else if (info.isDirectory()) {
+            await copyDirIfAbsent(source, target, copied);
+        }
+    }
+}
+async function copyDirIfAbsent(source, target, copied) {
+    const entries = await readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+        // 跳过原子写残留的临时文件与系统杂项。
+        if (entry.name.startsWith('.') || entry.name.endsWith('.tmp'))
+            continue;
+        const from = join(source, entry.name);
+        const to = join(target, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirIfAbsent(from, to, copied);
+        }
+        else if (entry.isFile()) {
+            await copyFileIfAbsent(from, to, copied);
+        }
+    }
+}
+async function copyFileIfAbsent(source, target, copied) {
+    if ((await stat(target).catch(() => null)) !== null)
+        return;
+    await mkdir(dirname(target), { recursive: true });
+    await copyFile(source, target);
+    copied.push(target);
+}
+/** 迁移未完成时清掉本次副本，让下次启动可以重新迁移（源文件始终不动）。 */
+async function rollback(files) {
+    for (const file of files)
+        await rm(file, { force: true }).catch(() => { });
+}

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,15 +6,26 @@
  * `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 = [
+    'unknown',
+    'available',
+    'downloaded',
+    'html-only',
+    'paywalled',
+    'blocked',
+    'failed',
+];
 const EXPORT_FORMATS = ['csv', 'ris', 'bibtex', 'md'];
 const CLEANUP_SCOPES = ['tasks', 'pdf', 'all'];
 const MAX_ANNOTATIONS = 50;
@@ -30,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')
@@ -521,6 +539,9 @@ function readResultsFilter(params) {
     const missingFullText = params.get('missingFullText');
     if (missingFullText === '1' || missingFullText === 'true')
         filter.missingFullText = true;
+    const pdfStatus = readEnum(params.get('pdfStatus') ?? undefined, 'pdfStatus', PDF_STATUSES);
+    if (pdfStatus !== undefined)
+        filter.pdfStatus = pdfStatus;
     const groupId = params.get('groupId')?.trim() ?? '';
     if (groupId !== '')
         filter.groupId = groupId;
@@ -549,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') {
@@ -558,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;
         }
@@ -617,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;
     }
@@ -658,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') {
@@ -667,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) {
@@ -699,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') {
@@ -725,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);
@@ -798,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

@@ -20,6 +20,8 @@ export interface PaperFilter {
     hasPdf?: boolean;
     /** 只保留尚无可用全文（PDF 或 EPMC HTML）的论文。 */
     missingFullText?: boolean;
+    /** 只保留有效全文状态恰为该值的论文（与覆盖率的 pdfStatusOf 同一口径）。 */
+    pdfStatus?: PdfStatus;
     /** 只保留归入该分组的论文。 */
     groupId?: string;
     /** 期刊/出处（精确匹配，不分大小写）。 */
@@ -35,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

@@ -38,6 +38,9 @@ export function filterPapers(task, filter = {}) {
             if (status === 'downloaded' || status === 'available' || status === 'html-only')
                 return false;
         }
+        if (filter.pdfStatus !== undefined && pdfStatusOf(task, paper) !== filter.pdfStatus) {
+            return false;
+        }
         if (filter.groupId !== undefined && task.states[paper.paperId]?.groupId !== filter.groupId) {
             return false;
         }
@@ -69,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 [
@@ -88,6 +132,7 @@ export function filterKey(filter) {
         filter.language ?? '',
         filter.hasPdf === true ? '1' : '',
         filter.missingFullText === true ? '1' : '',
+        filter.pdfStatus ?? '',
         filter.groupId ?? '',
         filter.venue ?? '',
         filter.author ?? '',