dsh-plugin-litsearch 0.0.0-stage → 0.2.0

package/lib/host/tasks/service.js

@@ -0,0 +1,976 @@
+/**
+ * TaskService：任务工作台的唯一事实源。
+ *
+ * 负责校验/规范化任务条件、维护内存与磁盘状态、串行化执行并广播 rev。
+ * 模型工具与面板 HTTP 路由都只调用这里，保证两边操作同一份状态。
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { MAX_LIMIT, PLUGIN_VERSION, 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';
+import { searchSources } from '../../search/aggregate.js';
+import { fullTextHtml, jatsToHtml, epmcXmlUrl } from '../../search/oa.js';
+import { fetchPubtatorEntities } from '../../search/pubtator-entities.js';
+import { SOURCE_IDS } from '../../search/types.js';
+import { TaskEvents } from '../events.js';
+import { buildExport } from '../export/index.js';
+import { cleanupPdfCache, epmcFullTextAvailable, persistPdf, probePdfRoot, readLocalPdf, readableFilename, resolvePdf, resolvePdfRoot, } from '../pdf/store.js';
+import { ZoteroConnector } from '../zotero/connector.js';
+import { compareTasks } from './compare.js';
+import { filterPapers } from './filter.js';
+import { TaskRunner } from './runner.js';
+import { computeStats } from './stats.js';
+import { applyAnnotations, countScreening, emptyState, normalizeGroups } from './states.js';
+import { TaskStore } from './store.js';
+import { cloneRound, roundsOf, toDetail, toSummary } from './summary.js';
+const MAX_QUERIES = 20;
+const MAX_TITLE = 120;
+const MAX_PAGE_LIMIT = 200;
+const MAX_TYPES = 20;
+const PROBE_QUERY = 'machine learning';
+export class TaskService {
+    ready;
+    store = new TaskStore();
+    events = new TaskEvents();
+    runner = new TaskRunner();
+    /**
+     * 全局「当前任务」：最后一次使用或打开的任务。
+     *
+     * 不按对话、也不按时间过期——同一主题的后续检索必须在原任务里加一轮，
+     * 跨对话、宿主重启都成立。只有用户显式新建任务或点开别的任务时才会改变。
+     */
+    currentTaskId;
+    currentTaskAt = 0;
+    constructor() {
+        this.ready = this.restore();
+    }
+    /**
+     * 先加载任务索引，再恢复「当前任务」快照。
+     *
+     * 快照缺失或指向已删除任务时，自举为最近更新的任务，避免下一轮检索
+     * 又新建一个同名任务。
+     */
+    async restore() {
+        try {
+            await this.store.load({
+                retentionDays: getSettings().taskRetentionDays,
+                retentionCount: getSettings().taskRetentionCount,
+            });
+        }
+        catch (error) {
+            console.warn('[dsh-plugin-litsearch] 任务目录加载失败：', error);
+        }
+        let restored = false;
+        try {
+            const snapshot = await this.store.loadCurrent();
+            if (snapshot?.current !== undefined &&
+                this.store.summary(snapshot.current.taskId) !== undefined) {
+                this.currentTaskId = snapshot.current.taskId;
+                this.currentTaskAt = snapshot.current.at;
+                restored = true;
+            }
+        }
+        catch (error) {
+            console.warn('[dsh-plugin-litsearch] 当前任务快照加载失败：', error);
+        }
+        if (!restored)
+            this.bootstrapCurrentTask();
+    }
+    /** 没有可用快照时，把最近更新的任务设为当前任务并落盘。 */
+    bootstrapCurrentTask() {
+        const latest = this.store.list()[0];
+        if (latest === undefined) {
+            // 任务已全部删除：清掉快照里的旧 id，避免 current.json 指向不存在的任务。
+            this.currentTaskId = undefined;
+            this.currentTaskAt = 0;
+            this.persistCurrent();
+            return;
+        }
+        this.currentTaskId = latest.id;
+        this.currentTaskAt = Date.parse(latest.updatedAt) || Date.now();
+        this.persistCurrent();
+    }
+    get globalRev() {
+        return this.events.currentRev;
+    }
+    get root() {
+        return this.store.root;
+    }
+    isRunning(id) {
+        return this.runner.isRunning(id);
+    }
+    health() {
+        const settings = getSettings();
+        return {
+            ok: true,
+            globalRev: this.events.currentRev,
+            sources: [...PROVIDER_INFOS],
+            sourceHealth: sourceHealthList(),
+            keys: { ncbi: settings.ncbiApiKey !== '', s2: settings.s2ApiKey !== '' },
+            settings: {
+                defaultSources: [...settings.defaultSources],
+                defaultPageSize: settings.defaultPageSize,
+                defaultSort: settings.defaultSort,
+                defaultLanguage: settings.defaultLanguage,
+                autoOpenTaskTab: settings.autoOpenTaskTab,
+                maxTaskTabs: settings.maxTaskTabs,
+            },
+            fullText: {
+                pdfRoot: resolvePdfRoot(),
+                pdfMaxMb: settings.pdfMaxMb,
+                autoDownload: settings.autoDownloadPdf,
+                epmcFulltext: settings.enableEpmcFulltext,
+            },
+            zotero: {
+                enabled: settings.zoteroEnabled,
+                baseUrl: settings.zoteroBaseUrl,
+                attachPdf: settings.zoteroAttachPdf,
+                tag: settings.zoteroTag,
+            },
+            storageDir: this.store.root,
+            version: PLUGIN_VERSION,
+        };
+    }
+    async eventsSince(sinceRev) {
+        await this.ready;
+        return this.events.since(sinceRev);
+    }
+    async list(filter = {}) {
+        await this.ready;
+        const needle = filter.q?.trim().toLowerCase() ?? '';
+        return this.store.list().filter((task) => {
+            if (filter.origin !== undefined && task.origin !== filter.origin)
+                return false;
+            if (filter.pinned !== undefined && task.pinned !== filter.pinned)
+                return false;
+            if (needle !== '' && !task.title.toLowerCase().includes(needle))
+                return false;
+            return true;
+        });
+    }
+    async get(id) {
+        await this.ready;
+        const task = this.store.cached(id) ?? (await this.store.loadTask(id));
+        if (task === undefined)
+            throw new SearchError('not_found', `任务不存在：${id}`);
+        // 旧版本落盘的任务没有 rounds，所有读路径统一补成数组。
+        if (!Array.isArray(task.rounds))
+            task.rounds = [];
+        return task;
+    }
+    async getDetail(id) {
+        return toDetail(await this.get(id));
+    }
+    /** 任务内轮次历史（时间升序、深拷贝）。 */
+    async getRounds(id) {
+        return roundsOf(await this.get(id)).map(cloneRound);
+    }
+    /**
+     * 当前任务：最近一次使用或打开的任务。
+     *
+     * 没有时间窗口、也不区分对话；只要任务还在就一直有效。任务被全部删除后
+     * 返回 undefined，由调用方决定是否新建。
+     */
+    async currentTask() {
+        await this.ready;
+        if (this.currentTaskId === undefined)
+            return undefined;
+        const task = await this.tryGet(this.currentTaskId);
+        if (task !== undefined)
+            return task;
+        this.currentTaskId = undefined;
+        this.bootstrapCurrentTask();
+        if (this.currentTaskId === undefined)
+            return undefined;
+        return this.tryGet(this.currentTaskId);
+    }
+    /** 记住最近使用的任务（下一次模型检索默认落在这里）。 */
+    setCurrentTask(id) {
+        this.currentTaskId = id;
+        this.currentTaskAt = Date.now();
+        this.persistCurrent();
+    }
+    /** 请求客户端打开/聚焦某任务 tab（面板被关掉时重新打开）。 */
+    focusTask(id, title, sessionId) {
+        this.events.requestFocus(id, title, sessionId);
+    }
+    persistCurrent() {
+        void this.store.saveCurrent({
+            version: 1,
+            ...(this.currentTaskId === undefined
+                ? {}
+                : { current: { taskId: this.currentTaskId, at: this.currentTaskAt } }),
+        });
+    }
+    /** 用户从任务列表点开某任务 = 进入该任务，之后的模型检索默认落在这里。 */
+    async activate(id) {
+        const task = await this.get(id);
+        this.setCurrentTask(task.id);
+        return task;
+    }
+    /** 等待该任务当前这一轮结束；返回是否确实已空闲。 */
+    async waitUntilIdle(id, timeoutMs, signal) {
+        if (!this.runner.isRunning(id))
+            return true;
+        if (signal?.aborted === true)
+            return false;
+        let timer;
+        let onAbort;
+        try {
+            await Promise.race([
+                this.runner.wait(id),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, Math.max(0, timeoutMs));
+                }),
+                ...(signal === undefined
+                    ? []
+                    : [
+                        new Promise((resolve) => {
+                            onAbort = () => resolve();
+                            signal.addEventListener('abort', onAbort, { once: true });
+                        }),
+                    ]),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (signal !== undefined && onAbort !== undefined) {
+                signal.removeEventListener('abort', onAbort);
+            }
+        }
+        return !this.runner.isRunning(id);
+    }
+    async create(input) {
+        await this.ready;
+        const settings = getSettings();
+        const conditions = this.readConditions(input, settings);
+        const title = readTitle(input.title, conditions);
+        const inherited = input.fromTaskId === undefined ? undefined : await this.get(input.fromTaskId);
+        const now = new Date().toISOString();
+        const task = {
+            id: `t${Date.now().toString(36)}${randomUUID().slice(0, 6)}`,
+            title,
+            conditions,
+            status: 'draft',
+            origin: input.origin,
+            rev: 1,
+            createdAt: now,
+            updatedAt: now,
+            pinned: false,
+            notes: '',
+            groups: [],
+            stats: {
+                perQuery: {},
+                rawHits: 0,
+                deduped: 0,
+                screening: { unread: 0, read: 0, included: 0, excluded: 0 },
+            },
+            result: { papers: [], sources: [] },
+            rounds: [],
+            states: inherited === undefined ? {} : inheritStates(inherited),
+            ...(input.fromTaskId === undefined ? {} : { fromTaskId: input.fromTaskId }),
+        };
+        this.store.put(task);
+        await this.store.save(task);
+        // 新建的任务就是「当前任务」：后续检索默认在它里面加轮次。
+        this.setCurrentTask(task.id);
+        this.events.publish(toSummary(task));
+        if (input.runNow !== false) {
+            void this.begin(task, 'new').catch((error) => {
+                console.warn('[dsh-plugin-litsearch] 任务执行失败：', error);
+            });
+        }
+        return task;
+    }
+    async update(id, patch, expectedRev) {
+        const task = await this.get(id);
+        if (expectedRev !== undefined && expectedRev !== task.rev) {
+            throw new SearchError('conflict', `任务已被更新（当前 rev=${task.rev}），请刷新后重试`);
+        }
+        if (this.runner.isRunning(id)) {
+            throw new SearchError('conflict', '任务正在运行，请等待完成或先取消');
+        }
+        if (patch.title !== undefined) {
+            const title = patch.title.trim();
+            if (title === '')
+                throw new SearchError('bad_request', '任务标题不能为空');
+            task.title = title.slice(0, MAX_TITLE);
+        }
+        if (patch.notes !== undefined)
+            task.notes = patch.notes;
+        if (patch.pinned !== undefined)
+            task.pinned = patch.pinned;
+        if (patch.groups !== undefined) {
+            const groups = normalizeGroups(patch.groups) ?? [];
+            task.groups = groups;
+            // 删除分组后，原来归入它的论文回到未分组，而不是指向不存在的 id。
+            const ids = new Set(groups.map((group) => group.id));
+            for (const state of Object.values(task.states)) {
+                if (state.groupId !== undefined && !ids.has(state.groupId))
+                    delete state.groupId;
+            }
+        }
+        if (patch.conditions !== undefined) {
+            task.conditions = mergeConditions(task.conditions, patch.conditions);
+        }
+        task.rev += 1;
+        task.updatedAt = new Date().toISOString();
+        await this.store.save(task);
+        this.events.publish(toSummary(task));
+        return task;
+    }
+    async remove(id) {
+        const task = await this.get(id);
+        // 先等这一轮收尾（finally 里还会落一次盘），再删文件，避免任务被写回。
+        if (this.runner.cancel(task.id))
+            await this.runner.wait(task.id);
+        await this.store.remove(task.id);
+        // 模型工具导出到 <storage>/out/<taskId>/ 的文件随任务一起清掉。
+        await rm(join(this.store.root, 'out', task.id), { recursive: true, force: true });
+        this.events.remove(task.id);
+        if (this.currentTaskId !== task.id)
+            return;
+        this.currentTaskId = undefined;
+        this.bootstrapCurrentTask();
+    }
+    /**
+     * 启动一次执行（任务内新一轮）；返回的 Promise 在运行结束后 resolve 为最新任务。
+     *
+     * 任务已缓存时同步登记运行态，调用方紧接着调 `waitUntilIdle` 也不会误判为空闲。
+     */
+    run(id, mode = 'new', origin = 'panel') {
+        const cached = this.store.cached(id);
+        if (cached !== undefined) {
+            try {
+                return this.begin(cached, mode, origin);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+        }
+        return this.get(id).then((task) => this.begin(task, mode, origin));
+    }
+    /**
+     * 在同一任务内开新一轮：全量替换检索条件后执行，**不新建任务、不新开 tab**。
+     *
+     * 与 `update` 的增量 patch 不同，这里按 CreateTaskInput 重算条件，缺省项回落到
+     * 当前设置而不是沿用旧值，保证「提交完整新条件」的语义明确。
+     */
+    async rerun(id, input, origin) {
+        const task = await this.get(id);
+        if (this.runner.isRunning(id)) {
+            throw new SearchError('conflict', '任务正在运行，请等待当前轮次结束');
+        }
+        const nextTitle = input.title?.trim() ?? '';
+        if (nextTitle !== '')
+            task.title = nextTitle.slice(0, MAX_TITLE);
+        task.conditions = this.readConditions(input, getSettings());
+        task.rev += 1;
+        task.updatedAt = new Date().toISOString();
+        await this.store.save(task);
+        this.events.publish(toSummary(task));
+        this.setCurrentTask(task.id);
+        return this.begin(task, 'new', origin);
+    }
+    async cancel(id) {
+        const task = await this.get(id);
+        if (!this.runner.cancel(id))
+            throw new SearchError('conflict', '任务未在运行');
+        return task;
+    }
+    async results(id, filter = {}) {
+        const task = await this.get(id);
+        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));
+        }
+        return {
+            taskId: task.id,
+            rev: task.rev,
+            total: papers.length,
+            offset,
+            limit,
+            papers: papers.slice(offset, offset + limit),
+        };
+    }
+    async stats(id, filter = {}, scope = 'task') {
+        const task = await this.get(id);
+        const base = await this.baseInfo(task);
+        const resolved = base === undefined ? filter : await this.withBaseFilter(task, filter);
+        return computeStats(task, resolved, scope, base);
+    }
+    /** 写入筛读 / 分组 / 必读 / 备注；返回新的 rev 与命中条数。 */
+    async annotate(id, inputs, expectedRev) {
+        const task = await this.get(id);
+        if (expectedRev !== undefined && expectedRev !== task.rev) {
+            throw new SearchError('conflict', `任务已被更新（当前 rev=${task.rev}），请刷新后重试`);
+        }
+        const outcome = applyAnnotations(task, inputs);
+        task.states = outcome.states;
+        task.stats.screening = countScreening(task.result.papers, task.states);
+        task.rev += 1;
+        task.updatedAt = new Date().toISOString();
+        await this.store.save(task);
+        this.events.publish(toSummary(task));
+        return { taskId: task.id, rev: task.rev, updated: outcome.updated };
+    }
+    async compare(id, withTaskId) {
+        if (withTaskId.trim() === '')
+            throw new SearchError('bad_request', '缺少对比任务 id');
+        if (withTaskId === id)
+            throw new SearchError('bad_request', '不能与自身对比');
+        const task = await this.get(id);
+        const base = await this.get(withTaskId);
+        return compareTasks(task, base);
+    }
+    /** 生成导出内容；`paperIds` 为空表示按当前筛选导出全部。 */
+    async export(id, format, filter = {}, paperIds) {
+        const task = await this.get(id);
+        const resolved = await this.withBaseFilter(task, filter);
+        let papers = filterPapers(task, resolved);
+        if (paperIds !== undefined && paperIds.length > 0) {
+            const wanted = new Set(paperIds);
+            papers = papers.filter((paper) => wanted.has(paper.paperId));
+        }
+        const base = task.fromTaskId === undefined ? undefined : await this.tryGet(task.fromTaskId);
+        const context = { task, papers, generatedAt: new Date() };
+        if (base !== undefined)
+            context.base = base;
+        return buildExport(context, format);
+    }
+    /** 把导出内容写到 `<storage>/out/<taskId>/`，供模型工具返回落盘路径。 */
+    async exportToDisk(id, format, filter = {}, paperIds) {
+        const task = await this.get(id);
+        const file = await this.export(id, format, filter, paperIds);
+        const dir = join(this.store.root, 'out', task.id);
+        await mkdir(dir, { recursive: true });
+        const path = join(dir, file.filename);
+        await writeFile(path, file.content, 'utf8');
+        let papers = filterPapers(task, await this.withBaseFilter(task, filter));
+        if (paperIds !== undefined && paperIds.length > 0) {
+            const wanted = new Set(paperIds);
+            papers = papers.filter((paper) => wanted.has(paper.paperId));
+        }
+        return { path, file, count: papers.length };
+    }
+    /** 设置页清理：任务文件与 PDF 缓存。 */
+    async cleanup(scope) {
+        if (scope === 'pdf') {
+            const outcome = await cleanupPdfCache(this.store.root);
+            return {
+                scope,
+                removed: outcome.removed,
+                freedBytes: outcome.freedBytes,
+                remaining: this.store.list().length,
+            };
+        }
+        const tasks = await this.store.cleanupUnpinned();
+        const pdf = scope === 'all' ? await cleanupPdfCache(this.store.root) : { removed: 0, freedBytes: 0 };
+        return {
+            scope,
+            removed: tasks.removed + pdf.removed,
+            freedBytes: tasks.freedBytes + pdf.freedBytes,
+            remaining: this.store.list().length,
+        };
+    }
+    /** 下载单篇 PDF；失败时写入失败状态，若有 EPMC 全文则降级为 html-only。 */
+    async downloadPdf(id, paperId) {
+        const task = await this.get(id);
+        const paper = findPaper(task, paperId);
+        const settings = getSettings();
+        const resolution = await resolvePdf(paper);
+        if (!resolution.ok || resolution.buffer === undefined) {
+            const fallback = settings.enableEpmcFulltext && epmcFullTextAvailable(paper) ? 'html-only' : resolution.status;
+            await this.setPdfState(task, paperId, {
+                pdfStatus: fallback,
+                pdfError: resolution.error ?? '下载失败',
+            });
+            const result = {
+                paperId,
+                status: fallback,
+                bytes: 0,
+                error: resolution.error ?? '下载失败',
+            };
+            return result;
+        }
+        const saved = await persistPdf(resolution.buffer, this.store.root, paper);
+        await this.setPdfState(task, paperId, {
+            pdfStatus: 'downloaded',
+            pdfFile: saved.filePath,
+        });
+        const result = {
+            paperId,
+            status: 'downloaded',
+            bytes: resolution.buffer.length,
+            filename: saved.filename,
+            path: saved.filePath,
+        };
+        if (resolution.url !== undefined)
+            result.url = resolution.url;
+        return result;
+    }
+    /** PDF 预览：优先用已落地文件；没有则临时抓取一次但不落盘。 */
+    async previewPdf(id, paperId) {
+        const task = await this.get(id);
+        const paper = findPaper(task, paperId);
+        const filename = readableFilename(paper);
+        const local = await readLocalPdf(paper);
+        if (local !== null)
+            return { buffer: local, filename };
+        const resolution = await resolvePdf(paper);
+        if (!resolution.ok || resolution.buffer === undefined) {
+            throw new SearchError('not_found', resolution.error ?? '没有可预览的 PDF');
+        }
+        return { buffer: resolution.buffer, filename };
+    }
+    /** Europe PMC 全文（JATS → 只含安全标签的 HTML）。 */
+    async fullText(id, paperId) {
+        const task = await this.get(id);
+        const paper = findPaper(task, paperId);
+        const settings = getSettings();
+        if (!settings.enableEpmcFulltext) {
+            throw new SearchError('not_found', 'Europe PMC 全文兜底已在设置中关闭');
+        }
+        const url = epmcXmlUrl(paper);
+        if (url === null)
+            throw new SearchError('not_found', '这篇文献没有 Europe PMC 全文');
+        // EPMC 的 JATS 全文经常 10s+，通用搜索超时对单篇阅读过紧。
+        const xml = await fetchEpmcXml(url, Math.max(settings.requestTimeoutMs, 30_000));
+        const html = fullTextHtml(paper, jatsToHtml(xml), 'Europe PMC');
+        const recorded = task.states[paperId]?.pdfStatus;
+        if (paper.pdfUrl === '' && (recorded === undefined || recorded === 'unknown' || recorded === 'failed')) {
+            await this.setPdfState(task, paperId, { pdfStatus: 'html-only' }).catch(() => undefined);
+        }
+        return html;
+    }
+    /** 单篇论文详情：独立论文页使用，含任务标题与分组。 */
+    async paperDetail(id, paperId) {
+        const task = await this.get(id);
+        const paper = findPaper(task, paperId);
+        const detail = {
+            taskId: task.id,
+            taskTitle: task.title,
+            rev: task.rev,
+            paper,
+            groups: task.groups,
+        };
+        const state = task.states[paperId];
+        if (state !== undefined)
+            detail.state = state;
+        return detail;
+    }
+    /** PubTator3 实体标注；无 PMID 时明确告知不可标注。 */
+    async entities(id, paperId, signal) {
+        const task = await this.get(id);
+        const paper = findPaper(task, paperId);
+        const pmid = paper.ids.pmid;
+        if (pmid === '') {
+            throw new SearchError('not_found', '这篇文献没有 PMID，PubTator 无法标注');
+        }
+        const settings = getSettings();
+        // 全文标注的 BioC JSON 可能较大，沿用全文的 30s 下限。
+        const entities = await fetchPubtatorEntities(pmid, Math.max(settings.requestTimeoutMs, 30_000), signal);
+        return { paperId, pmid, entities, fetchedAt: new Date().toISOString() };
+    }
+    /** 测试 Zotero connector 是否可达，并返回当前选中的分类。 */
+    async zoteroProbe() {
+        const settings = getSettings();
+        try {
+            return await new ZoteroConnector(settings.zoteroBaseUrl).probe();
+        }
+        catch (error) {
+            return { ok: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /** 把选中论文同步到 Zotero（含本地 PDF 附件）。 */
+    async zoteroSync(id, paperIds) {
+        const settings = getSettings();
+        if (!settings.zoteroEnabled)
+            throw new SearchError('bad_request', 'Zotero 同步已在设置中关闭');
+        const task = await this.get(id);
+        const wanted = paperIds === undefined || paperIds.length === 0
+            ? task.result.papers.slice(0, 50)
+            : paperIds.map((paperId) => findPaper(task, paperId));
+        if (wanted.length === 0)
+            throw new SearchError('bad_request', '没有可同步的文献');
+        const connector = new ZoteroConnector(settings.zoteroBaseUrl);
+        const probe = await connector.probe();
+        if (!probe.ok) {
+            throw new SearchError('network_error', `Zotero 未运行或 connector 不可达：${probe.error ?? settings.zoteroBaseUrl}`);
+        }
+        const readOnlyAttachments = settings.zoteroAttachPdf && probe.collection?.filesEditable === false;
+        const attachPdf = settings.zoteroAttachPdf && !readOnlyAttachments;
+        const inputs = [];
+        for (const paper of wanted) {
+            const tags = task.states[paper.paperId]?.tags ?? [];
+            const pdfPath = attachPdf ? await this.ensureLocalPdf(paper) : undefined;
+            inputs.push({ paper, tags, ...(pdfPath === undefined ? {} : { pdfPath }) });
+        }
+        try {
+            const result = await connector.sync(inputs, {
+                baseUrl: settings.zoteroBaseUrl,
+                attachPdf,
+                tag: settings.zoteroTag,
+            });
+            if (probe.collection === undefined) {
+                result.messages.unshift('Zotero 当前未选择分类，条目已保存到「我的文库」');
+            }
+            else if (readOnlyAttachments) {
+                result.messages.unshift('当前分类不可写附件，已只保存条目；可在 Zotero 中换一个可写分类后重试');
+            }
+            return result;
+        }
+        catch (error) {
+            throw new SearchError('upstream_error', error instanceof Error ? error.message : String(error));
+        }
+    }
+    /** 下载目录可写性测试（设置页）。 */
+    async storageProbe() {
+        const outcome = await probePdfRoot();
+        if (outcome.writable)
+            return { ok: true, root: outcome.root, writable: true };
+        return {
+            ok: false,
+            root: outcome.root,
+            writable: false,
+            ...(outcome.error === undefined ? {} : { error: outcome.error }),
+        };
+    }
+    async ensureLocalPdf(paper) {
+        const local = await readLocalPdf(paper);
+        if (local !== null)
+            return join(resolvePdfRoot(), readableFilename(paper));
+        const resolution = await resolvePdf(paper).catch(() => null);
+        if (resolution === null || !resolution.ok || resolution.buffer === undefined)
+            return undefined;
+        const saved = await persistPdf(resolution.buffer, this.store.root, paper);
+        return saved.filePath;
+    }
+    async setPdfState(task, paperId, patch) {
+        // 下载进行中任务被删除：不再写回，也不向客户端广播已删除的任务。
+        if (this.store.summary(task.id) === undefined)
+            return;
+        const current = task.states[paperId] ?? emptyState();
+        const next = { ...current, pdfStatus: patch.pdfStatus };
+        if (patch.pdfError === undefined)
+            delete next.pdfError;
+        else
+            next.pdfError = patch.pdfError.slice(0, 300);
+        if (patch.pdfFile === undefined)
+            delete next.pdfFile;
+        else
+            next.pdfFile = patch.pdfFile.slice(0, 1024);
+        task.states[paperId] = next;
+        task.rev += 1;
+        task.updatedAt = new Date().toISOString();
+        await this.store.save(task);
+        this.events.publish(toSummary(task));
+    }
+    /** 单源诊断：用固定短查询测一次连通性与延迟（不受冷却影响）。 */
+    async probe(source) {
+        if (!SOURCE_IDS.includes(source)) {
+            throw new SearchError('bad_request', `未知数据源：${source}`);
+        }
+        const settings = getSettings();
+        const started = Date.now();
+        const result = { target: source, ok: false, latencyMs: 0, count: 0 };
+        try {
+            const [outcome] = await searchSources({
+                query: PROBE_QUERY,
+                sources: [source],
+                limit: 1,
+                openAccessOnly: false,
+                contactEmail: settings.contactEmail,
+                timeoutMs: Math.min(settings.requestTimeoutMs, 20_000),
+                bypassCooldown: true,
+            });
+            result.latencyMs = Date.now() - started;
+            if (outcome === undefined || !outcome.ok) {
+                result.error = outcome?.error ?? '未返回结果';
+            }
+            else {
+                result.ok = true;
+                result.count = outcome.records.length;
+            }
+        }
+        catch (error) {
+            result.latencyMs = Date.now() - started;
+            result.error = error instanceof Error ? error.message : String(error);
+        }
+        const until = cooldownUntil(source);
+        if (until > Date.now())
+            result.cooldownUntil = new Date(until).toISOString();
+        return result;
+    }
+    async tryGet(id) {
+        try {
+            return await this.get(id);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async baseInfo(task) {
+        if (task.fromTaskId === undefined)
+            return undefined;
+        const base = await this.tryGet(task.fromTaskId);
+        if (base === undefined)
+            return undefined;
+        return { paperIds: new Set(base.result.papers.map((paper) => paper.paperId)), rev: base.rev };
+    }
+    /** `newOnly` 需要基准任务的论文集合；基准已删除时忽略该条件。 */
+    async withBaseFilter(task, filter) {
+        if (filter.newOnly !== true || task.fromTaskId === undefined)
+            return filter;
+        const base = await this.tryGet(task.fromTaskId);
+        if (base === undefined)
+            return filter;
+        return {
+            ...filter,
+            newPaperIds: new Set(base.result.papers.map((paper) => paper.paperId)),
+        };
+    }
+    dispose() {
+        this.runner.cancelAll();
+        void this.store.flush();
+    }
+    begin(task, mode, origin = task.origin) {
+        if (this.runner.isRunning(task.id)) {
+            throw new SearchError('conflict', '任务正在运行');
+        }
+        if (mode === 'more') {
+            throw new SearchError('bad_request', '续页加载将在后续版本提供，请先重跑任务');
+        }
+        const queries = task.conditions.queries.filter((query) => query.enabled && query.text.trim() !== '');
+        if (queries.length === 0)
+            throw new SearchError('bad_request', '没有启用的检索式');
+        const done = this.runner.start(task, {
+            persist: (current) => this.store.save(current),
+            publish: (current) => {
+                // 删除后这一轮收尾仍会 publish，跳过已删除任务，避免客户端又去打开它。
+                if (this.store.summary(current.id) !== undefined) {
+                    this.events.publish(toSummary(current));
+                }
+            },
+        }, origin);
+        return done.then(() => {
+            if (getSettings().autoDownloadPdf) {
+                void this.autoDownloadPdfs(task).catch((error) => {
+                    console.warn('[dsh-plugin-litsearch] 自动下载 PDF 失败：', error);
+                });
+            }
+            return task;
+        });
+    }
+    /** 任务完成后按设置自动下载少量开放获取 PDF（上限 10 篇，避免长时间占用网络）。 */
+    async autoDownloadPdfs(task) {
+        const targets = task.result.papers
+            .filter((paper) => paper.pdfUrl !== '' || paper.ids.pmcid !== '' || paper.ids.arxivId !== '')
+            .slice(0, 10);
+        for (const paper of targets) {
+            // 任务中途被删除时停止后续下载，避免继续往用户下载目录写文件。
+            if (this.store.summary(task.id) === undefined)
+                return;
+            if (task.states[paper.paperId]?.pdfStatus === 'downloaded')
+                continue;
+            const resolution = await resolvePdf(paper).catch(() => null);
+            if (resolution === null || !resolution.ok || resolution.buffer === undefined) {
+                if (resolution !== null) {
+                    const fallback = getSettings().enableEpmcFulltext && epmcFullTextAvailable(paper)
+                        ? 'html-only'
+                        : resolution.status;
+                    await this.setPdfState(task, paper.paperId, {
+                        pdfStatus: fallback,
+                        pdfError: resolution.error ?? '下载失败',
+                    }).catch(() => undefined);
+                }
+                continue;
+            }
+            const saved = await persistPdf(resolution.buffer, this.store.root, paper);
+            await this.setPdfState(task, paper.paperId, {
+                pdfStatus: 'downloaded',
+                pdfFile: saved.filePath,
+            }).catch(() => undefined);
+        }
+    }
+    readConditions(input, settings) {
+        const queries = normalizeQueries(input.query, input.queries);
+        const sources = normalizeSources(input.sources, settings.defaultSources);
+        const condition = {
+            queries,
+            sources,
+            openAccessOnly: input.openAccessOnly === true,
+            language: input.language ?? settings.defaultLanguage,
+            sort: input.sort ?? settings.defaultSort,
+            pageSize: clampInt(input.pageSize ?? settings.defaultPageSize, 1, MAX_LIMIT),
+        };
+        if (input.yearFrom !== undefined)
+            condition.yearFrom = input.yearFrom;
+        if (input.yearTo !== undefined)
+            condition.yearTo = input.yearTo;
+        const types = normalizeTypes(input.types);
+        if (types !== undefined)
+            condition.types = types;
+        if (condition.yearFrom !== undefined && condition.yearTo !== undefined && condition.yearFrom > condition.yearTo) {
+            throw new SearchError('bad_request', '起始年份不能晚于结束年份');
+        }
+        return condition;
+    }
+}
+function mergeConditions(current, patch) {
+    const next = {
+        ...current,
+        queries: patch.queries === undefined ? current.queries : normalizeQueries(undefined, patch.queries),
+        sources: normalizeSources(patch.sources, current.sources),
+        pageSize: clampInt(patch.pageSize ?? current.pageSize, 1, MAX_LIMIT),
+        openAccessOnly: patch.openAccessOnly ?? current.openAccessOnly,
+        language: patch.language ?? current.language,
+        sort: patch.sort ?? current.sort,
+    };
+    if (patch.yearFrom === null)
+        delete next.yearFrom;
+    else if (patch.yearFrom !== undefined)
+        next.yearFrom = patch.yearFrom;
+    if (patch.yearTo === null)
+        delete next.yearTo;
+    else if (patch.yearTo !== undefined)
+        next.yearTo = patch.yearTo;
+    if (patch.types === null)
+        delete next.types;
+    else if (patch.types !== undefined) {
+        const types = normalizeTypes(patch.types);
+        if (types === undefined)
+            delete next.types;
+        else
+            next.types = types;
+    }
+    if (next.yearFrom !== undefined && next.yearTo !== undefined && next.yearFrom > next.yearTo) {
+        throw new SearchError('bad_request', '起始年份不能晚于结束年份');
+    }
+    return next;
+}
+function normalizeQueries(query, queries) {
+    const raw = [];
+    if (queries !== undefined && queries.length > 0)
+        raw.push(...queries);
+    else if (query !== undefined && query.trim() !== '')
+        raw.push({ text: query });
+    if (raw.length === 0)
+        throw new SearchError('bad_request', '请至少提供一条检索式');
+    if (raw.length > MAX_QUERIES) {
+        throw new SearchError('bad_request', `检索式最多 ${MAX_QUERIES} 条`);
+    }
+    return raw.map((input, index) => {
+        const text = input.text.trim();
+        if (text === '')
+            throw new SearchError('bad_request', `第 ${index + 1} 条检索式为空`);
+        const name = input.name?.trim() ?? '';
+        return {
+            id: `q${index + 1}`,
+            name: name === '' ? `检索式 ${index + 1}` : name,
+            text,
+            enabled: input.enabled !== false,
+            ...(input.perSource === undefined ? {} : { perSource: { ...input.perSource } }),
+        };
+    });
+}
+function normalizeSources(requested, fallback) {
+    const wanted = requested === undefined || requested.length === 0 ? fallback : requested;
+    const valid = SOURCE_IDS.filter((id) => wanted.includes(id));
+    return valid.length === 0 ? [...SOURCE_IDS] : valid;
+}
+function normalizeTypes(values) {
+    if (values === undefined)
+        return undefined;
+    const seen = new Set();
+    for (const raw of values) {
+        const value = raw.trim().slice(0, 40);
+        if (value !== '')
+            seen.add(value);
+        if (seen.size >= MAX_TYPES)
+            break;
+    }
+    return seen.size === 0 ? undefined : [...seen];
+}
+function readTitle(title, conditions) {
+    const explicit = title?.trim() ?? '';
+    if (explicit !== '')
+        return explicit.slice(0, MAX_TITLE);
+    const first = conditions.queries[0]?.text ?? '未命名检索';
+    const suffix = conditions.queries.length > 1 ? ` 等 ${conditions.queries.length} 条` : '';
+    const base = first.length > 60 ? `${first.slice(0, 60)}…` : first;
+    return `${base}${suffix}`.slice(0, MAX_TITLE);
+}
+function inheritStates(base) {
+    const states = {};
+    for (const [paperId, state] of Object.entries(base.states)) {
+        // 分组是任务内概念，继承时只带筛读、必读顺序、备注与标签。
+        const next = { screening: state.screening };
+        if (state.shortlistOrder !== undefined)
+            next.shortlistOrder = state.shortlistOrder;
+        if (state.note !== undefined)
+            next.note = state.note;
+        if (state.tags !== undefined)
+            next.tags = [...state.tags];
+        states[paperId] = next;
+    }
+    return states;
+}
+function clampInt(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(Math.max(Math.floor(value), min), max);
+}
+function findPaper(task, paperId) {
+    const paper = task.result.papers.find((entry) => entry.paperId === paperId);
+    if (paper === undefined)
+        throw new SearchError('not_found', `任务里没有这篇文献：${paperId}`);
+    return paper;
+}
+async function fetchEpmcXml(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), Math.max(5_000, timeoutMs));
+    try {
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: { accept: 'application/xml,text/xml;q=0.9,*/*;q=0.5' },
+        });
+        if (!response.ok) {
+            const code = response.status === 404 ? 'not_found' : 'upstream_error';
+            throw new SearchError(code, `Europe PMC 返回 HTTP ${response.status}`);
+        }
+        const declared = Number(response.headers.get('content-length') ?? '0');
+        if (Number.isFinite(declared) && declared > 6 * 1024 * 1024) {
+            throw new SearchError('bad_request', 'Europe PMC 全文超过 6 MB，已跳过');
+        }
+        const text = await response.text();
+        if (text.length > 6 * 1024 * 1024) {
+            throw new SearchError('bad_request', 'Europe PMC 全文超过 6 MB，已跳过');
+        }
+        if (!text.includes('<body')) {
+            throw new SearchError('not_found', 'Europe PMC 没有可用的全文 XML');
+        }
+        return text;
+    }
+    catch (error) {
+        if (error instanceof SearchError)
+            throw error;
+        if (controller.signal.aborted) {
+            throw new SearchError('timeout', 'Europe PMC 全文请求超时');
+        }
+        throw new SearchError('network_error', error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}