dsh-plugin-litsearch 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,8 @@
+/**
+ * 任务对比：按稳定的 `paperId` 做差分，标出新增 / 共有 / 缺失。
+ *
+ * 对比只读两份已加载结果，不触发重新检索；新增结果可回到结果页用 `new=1`
+ * 筛选，或由模型/面板批量写入筛读状态。
+ */
+import type { CompareResult, SearchTask } from '../../search/types.js';
+export declare function compareTasks(task: SearchTask, base: SearchTask): CompareResult;

package/lib/host/tasks/compare.js

@@ -0,0 +1,49 @@
+/**
+ * 任务对比：按稳定的 `paperId` 做差分，标出新增 / 共有 / 缺失。
+ *
+ * 对比只读两份已加载结果，不触发重新检索；新增结果可回到结果页用 `new=1`
+ * 筛选，或由模型/面板批量写入筛读状态。
+ */
+export function compareTasks(task, base) {
+    const currentIds = new Set(task.result.papers.map((paper) => paper.paperId));
+    const baseIds = new Set(base.result.papers.map((paper) => paper.paperId));
+    let common = 0;
+    const added = [];
+    const missing = [];
+    for (const paper of task.result.papers) {
+        if (baseIds.has(paper.paperId))
+            common += 1;
+        else
+            added.push(toComparePaper(paper));
+    }
+    for (const paper of base.result.papers) {
+        if (!currentIds.has(paper.paperId))
+            missing.push(toComparePaper(paper));
+    }
+    return {
+        taskId: task.id,
+        rev: task.rev,
+        withTaskId: base.id,
+        withTitle: base.title,
+        counts: {
+            added: added.length,
+            common,
+            missing: missing.length,
+            total: task.result.papers.length,
+            baseTotal: base.result.papers.length,
+        },
+        added,
+        missing,
+    };
+}
+function toComparePaper(paper) {
+    return {
+        paperId: paper.paperId,
+        title: paper.title,
+        authors: paper.authors.slice(0, 6),
+        year: paper.year,
+        venue: paper.venue,
+        doi: paper.doi,
+        openAccess: paper.openAccess,
+    };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * 结果筛选：`/results` 与 `/stats` 共用同一份口径。
+ *
+ * 任何新筛选条件都必须先加到这里，避免列表与统计出现两套过滤逻辑。
+ */
+import type { Paper, PdfStatus, Screening, SearchTask, TaskLanguage } from '../../search/types.js';
+export interface PaperFilter {
+    source?: string;
+    yearFrom?: number;
+    yearTo?: number;
+    openAccessOnly?: boolean;
+    q?: string;
+    screening?: Screening;
+    /** 只保留命中该检索式的论文。 */
+    queryId?: string;
+    /** 文献类型（精确匹配，不分大小写）。 */
+    type?: string;
+    language?: TaskLanguage;
+    /** 只保留已有 PDF 直链或已下载的论文。 */
+    hasPdf?: boolean;
+    /** 只保留尚无可用全文（PDF 或 EPMC HTML）的论文。 */
+    missingFullText?: boolean;
+    /** 只保留有效全文状态恰为该值的论文（与覆盖率的 pdfStatusOf 同一口径）。 */
+    pdfStatus?: PdfStatus;
+    /** 只保留归入该分组的论文。 */
+    groupId?: string;
+    /** 期刊/出处（精确匹配，不分大小写）。 */
+    venue?: string;
+    /** 作者（仅匹配 authors 中的完整姓名，不分大小写）。 */
+    author?: string;
+    /** 只保留相对 `fromTaskId` 新增的论文。 */
+    newOnly?: boolean;
+    /** 由服务层按基准任务解析出的新增集合；不参与指纹。 */
+    newPaperIds?: ReadonlySet<string>;
+}
+export declare function filterPapers(task: SearchTask, filter?: PaperFilter): Paper[];
+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;
+/** 稳定的筛选指纹（统计缓存 key 的一部分）。 */
+export declare function filterKey(filter: PaperFilter): string;

package/lib/host/tasks/filter.js

@@ -0,0 +1,100 @@
+/**
+ * 结果筛选：`/results` 与 `/stats` 共用同一份口径。
+ *
+ * 任何新筛选条件都必须先加到这里，避免列表与统计出现两套过滤逻辑。
+ */
+export function filterPapers(task, filter = {}) {
+    const needle = filter.q?.trim().toLowerCase() ?? '';
+    const type = filter.type?.trim().toLowerCase() ?? '';
+    const venue = filter.venue?.trim().toLowerCase() ?? '';
+    const author = filter.author?.trim().toLowerCase() ?? '';
+    return task.result.papers.filter((paper) => {
+        if (filter.source !== undefined && !paper.hitSources.some((hit) => hit.source === filter.source)) {
+            return false;
+        }
+        if (filter.yearFrom !== undefined && (paper.year ?? 0) < filter.yearFrom)
+            return false;
+        if (filter.yearTo !== undefined && (paper.year ?? Number.MAX_SAFE_INTEGER) > filter.yearTo) {
+            return false;
+        }
+        if (filter.openAccessOnly === true && !paper.openAccess)
+            return false;
+        if (filter.queryId !== undefined && !paper.matchedQueries.includes(filter.queryId))
+            return false;
+        if (type !== '' && paper.type.toLowerCase() !== type)
+            return false;
+        if (venue !== '' && paper.venue.trim().toLowerCase() !== venue)
+            return false;
+        if (author !== '' && !paper.authors.some((name) => name.trim().toLowerCase() === author)) {
+            return false;
+        }
+        if (filter.language !== undefined && !matchesLanguage(paper, filter.language))
+            return false;
+        if (filter.hasPdf === true && pdfStatusOf(task, paper) !== 'downloaded' && paper.pdfUrl === '') {
+            return false;
+        }
+        if (filter.missingFullText === true) {
+            const status = pdfStatusOf(task, paper);
+            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;
+        }
+        if (filter.newOnly === true) {
+            const base = filter.newPaperIds;
+            if (base !== undefined && base.has(paper.paperId))
+                return false;
+        }
+        if (filter.screening !== undefined && screeningOf(task, paper) !== filter.screening)
+            return false;
+        if (needle !== '') {
+            const haystack = `${paper.title}\n${paper.abstract}`.toLowerCase();
+            if (!haystack.includes(needle))
+                return false;
+        }
+        return true;
+    });
+}
+export function screeningOf(task, paper) {
+    return task.states[paper.paperId]?.screening ?? 'unread';
+}
+/** 有效全文状态：没有人工/下载记录时，上游给的 PDF 直链视为可用。 */
+export function pdfStatusOf(task, paper) {
+    const recorded = task.states[paper.paperId]?.pdfStatus;
+    if (recorded !== undefined)
+        return recorded;
+    return paper.pdfUrl === '' ? 'unknown' : 'available';
+}
+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');
+}
+/** 稳定的筛选指纹（统计缓存 key 的一部分）。 */
+export function filterKey(filter) {
+    return [
+        filter.source ?? '',
+        filter.yearFrom ?? '',
+        filter.yearTo ?? '',
+        filter.openAccessOnly === true ? '1' : '',
+        filter.q ?? '',
+        filter.screening ?? '',
+        filter.queryId ?? '',
+        filter.type ?? '',
+        filter.language ?? '',
+        filter.hasPdf === true ? '1' : '',
+        filter.missingFullText === true ? '1' : '',
+        filter.pdfStatus ?? '',
+        filter.groupId ?? '',
+        filter.venue ?? '',
+        filter.author ?? '',
+        filter.newOnly === true ? '1' : '',
+    ].join('|');
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 任务内检索轮次的纯逻辑。
+ *
+ * 这里只依赖类型（type-only import），不引入任何运行时模块，因此单测可以
+ * 直接 import 源码，不必先编译出 lib/。轮数上限由调用方从配置注入。
+ */
+import type { SearchRound, SearchTask, TaskConditions, TaskOrigin } from '../../search/types.js';
+/** 旧版本落盘的任务没有 rounds；所有读取路径统一按空数组兼容。 */
+export declare function roundsOf(task: SearchTask): SearchRound[];
+/**
+ * 条件深拷贝。
+ *
+ * 轮次快照必须使用它：`queries[].perSource`、`types`、`sources` 都是可变引用，
+ * 浅拷贝会让历史轮次的条件跟着后续编辑一起变。
+ */
+export declare function cloneConditions(conditions: TaskConditions): TaskConditions;
+/** 轮次深拷贝，避免投影对象与内存任务共享条件引用。 */
+export declare function cloneRound(round: SearchRound): SearchRound;
+/** 只保留最近 max 轮；返回新数组（调用方负责写回）。 */
+export declare function trimRoundList(rounds: SearchRound[], max: number): SearchRound[];
+/**
+ * 开跑前挂一条轮次快照，返回该轮对象供结束时回填。
+ *
+ * 序号取「上一轮 index + 1」，即使旧轮次被裁剪也不会复用旧号。
+ */
+export declare function startRound(task: SearchTask, origin: TaskOrigin, max: number, now?: string): SearchRound;
+/** 无论成功 / 取消 / 异常都回填本轮元数据，时间轴不会留下「永远运行中」。 */
+export declare function finishRound(round: SearchRound, task: SearchTask, now?: string): void;

package/lib/host/tasks/rounds.js

@@ -0,0 +1,74 @@
+/**
+ * 任务内检索轮次的纯逻辑。
+ *
+ * 这里只依赖类型（type-only import），不引入任何运行时模块，因此单测可以
+ * 直接 import 源码，不必先编译出 lib/。轮数上限由调用方从配置注入。
+ */
+/** 旧版本落盘的任务没有 rounds；所有读取路径统一按空数组兼容。 */
+export function roundsOf(task) {
+    return Array.isArray(task.rounds) ? task.rounds : [];
+}
+/**
+ * 条件深拷贝。
+ *
+ * 轮次快照必须使用它：`queries[].perSource`、`types`、`sources` 都是可变引用，
+ * 浅拷贝会让历史轮次的条件跟着后续编辑一起变。
+ */
+export function cloneConditions(conditions) {
+    return {
+        ...conditions,
+        queries: conditions.queries.map((query) => ({
+            ...query,
+            ...(query.perSource === undefined ? {} : { perSource: { ...query.perSource } }),
+        })),
+        sources: [...conditions.sources],
+        ...(conditions.types === undefined ? {} : { types: [...conditions.types] }),
+    };
+}
+/** 轮次深拷贝，避免投影对象与内存任务共享条件引用。 */
+export function cloneRound(round) {
+    return {
+        ...round,
+        conditions: cloneConditions(round.conditions),
+        ...(round.stats === undefined
+            ? {}
+            : { stats: { ...round.stats, perQuery: { ...round.stats.perQuery } } }),
+    };
+}
+/** 只保留最近 max 轮；返回新数组（调用方负责写回）。 */
+export function trimRoundList(rounds, max) {
+    return rounds.length <= max ? rounds : rounds.slice(rounds.length - max);
+}
+/**
+ * 开跑前挂一条轮次快照，返回该轮对象供结束时回填。
+ *
+ * 序号取「上一轮 index + 1」，即使旧轮次被裁剪也不会复用旧号。
+ */
+export function startRound(task, origin, max, now = new Date().toISOString()) {
+    const previous = roundsOf(task);
+    const index = previous.length > 0 ? previous[previous.length - 1].index + 1 : 1;
+    const round = {
+        id: `r${index}`,
+        index,
+        createdAt: now,
+        origin,
+        conditions: cloneConditions(task.conditions),
+    };
+    task.rounds = trimRoundList([...previous, round], max);
+    return round;
+}
+/** 无论成功 / 取消 / 异常都回填本轮元数据，时间轴不会留下「永远运行中」。 */
+export function finishRound(round, task, now = new Date().toISOString()) {
+    round.finishedAt = now;
+    round.status = task.status;
+    round.stats = {
+        rawHits: task.stats.rawHits,
+        deduped: task.stats.deduped,
+        loaded: task.result.papers.length,
+        perQuery: { ...task.stats.perQuery },
+    };
+    round.skippedSources = task.result.sources.filter((source) => source.skipped === true).length;
+    round.failedSources = task.result.sources.filter((source) => !source.ok && source.skipped !== true).length;
+    if (task.error !== undefined)
+        round.error = task.error;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * 任务执行器。
+ *
+ * 多检索式按「先 query 后 source」串行扇出（每条式内部并发各源），每完成一条
+ * 式就自增 rev 并持久化，客户端据此显示 i/N 进度。取消通过 AbortSignal 透传到
+ * 每个上游请求；已拿到的结果保留，状态标 `canceled`。
+ */
+import type { SearchTask, TaskOrigin } from '../../search/types.js';
+export interface RunnerHooks {
+    persist(task: SearchTask): Promise<void>;
+    publish(task: SearchTask): void;
+}
+export declare class TaskRunner {
+    private readonly controllers;
+    /** 正在执行的那一轮的完成 Promise，供「等待上一轮结束」使用。 */
+    private readonly running;
+    isRunning(id: string): boolean;
+    /** 返回当前这一轮的完成 Promise；空闲时立即 resolve。 */
+    wait(id: string): Promise<void>;
+    /** 中止运行；返回是否确实有任务在跑。 */
+    cancel(id: string): boolean;
+    cancelAll(): void;
+    /**
+     * 启动一次执行（= 任务内新开一轮）；controller 同步登记，因此调用方返回时
+     * `isRunning` 已为 true。`origin` 记录这一轮是谁发起的，用于历史时间轴。
+     */
+    start(task: SearchTask, hooks: RunnerHooks, origin?: TaskOrigin): Promise<void>;
+    private execute;
+}

package/lib/host/tasks/runner.js

@@ -0,0 +1,208 @@
+/**
+ * 任务执行器。
+ *
+ * 多检索式按「先 query 后 source」串行扇出（每条式内部并发各源），每完成一条
+ * 式就自增 rev 并持久化，客户端据此显示 i/N 进度。取消通过 AbortSignal 透传到
+ * 每个上游请求；已拿到的结果保留，状态标 `canceled`。
+ */
+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 { finishRound, startRound } from './rounds.js';
+import { countScreening } from './states.js';
+class RunCanceled extends Error {
+    constructor() {
+        super('检索已取消');
+        this.name = 'RunCanceled';
+    }
+}
+export class TaskRunner {
+    controllers = new Map();
+    /** 正在执行的那一轮的完成 Promise，供「等待上一轮结束」使用。 */
+    running = new Map();
+    isRunning(id) {
+        return this.controllers.has(id);
+    }
+    /** 返回当前这一轮的完成 Promise；空闲时立即 resolve。 */
+    wait(id) {
+        return this.running.get(id) ?? Promise.resolve();
+    }
+    /** 中止运行；返回是否确实有任务在跑。 */
+    cancel(id) {
+        const controller = this.controllers.get(id);
+        if (controller === undefined)
+            return false;
+        controller.abort();
+        return true;
+    }
+    cancelAll() {
+        for (const controller of this.controllers.values())
+            controller.abort();
+    }
+    /**
+     * 启动一次执行（= 任务内新开一轮）；controller 同步登记，因此调用方返回时
+     * `isRunning` 已为 true。`origin` 记录这一轮是谁发起的，用于历史时间轴。
+     */
+    start(task, hooks, origin = task.origin) {
+        const controller = new AbortController();
+        this.controllers.set(task.id, controller);
+        const done = this.execute(task, hooks, controller, origin).finally(() => {
+            this.controllers.delete(task.id);
+            this.running.delete(task.id);
+        });
+        this.running.set(task.id, done);
+        return done;
+    }
+    async execute(task, hooks, controller, origin) {
+        const queries = task.conditions.queries.filter((query) => query.enabled && query.text.trim() !== '');
+        if (queries.length === 0)
+            throw new Error('没有启用的检索式');
+        // 开跑前先落一条轮次快照：条件是深拷贝，之后改条件不会影响历史。
+        const round = startRound(task, origin, DEFAULT_TASK_MAX_ROUNDS);
+        task.status = 'running';
+        task.error = undefined;
+        task.result.papers = [];
+        task.result.sources = [];
+        task.result.fetchedAt = undefined;
+        task.stats = {
+            perQuery: {},
+            rawHits: 0,
+            deduped: 0,
+            screening: { unread: 0, read: 0, included: 0, excluded: 0 },
+        };
+        task.progress = { queryIndex: 0, queryTotal: queries.length };
+        touch(task, hooks);
+        await hooks.persist(task);
+        const hits = [];
+        const statusById = new Map();
+        const perSourceLimit = clampRequestLimit(task.conditions.pageSize);
+        try {
+            for (const [index, query] of queries.entries()) {
+                task.progress = { queryIndex: index + 1, queryTotal: queries.length };
+                touch(task, hooks);
+                await hooks.persist(task);
+                const results = await searchSources({
+                    query: query.text,
+                    perSource: query.perSource,
+                    sources: task.conditions.sources,
+                    limit: perSourceLimit,
+                    yearFrom: task.conditions.yearFrom,
+                    yearTo: task.conditions.yearTo,
+                    openAccessOnly: task.conditions.openAccessOnly,
+                    contactEmail: '',
+                    timeoutMs: 0,
+                    signal: controller.signal,
+                });
+                if (controller.signal.aborted)
+                    throw new RunCanceled();
+                for (const result of results) {
+                    const records = result.records.filter((record) => matchesConditions(record, task.conditions));
+                    const status = statusById.get(result.source) ?? {
+                        id: result.source,
+                        ok: true,
+                        count: 0,
+                    };
+                    if (records.length < result.records.length)
+                        status.filtered = true;
+                    status.count += records.length;
+                    if (result.skipped === true) {
+                        // 限流跳过不是故障：不标 failed、不进 partial，只留中性说明。
+                        status.skipped = true;
+                        status.note = result.error;
+                    }
+                    else if (!result.ok) {
+                        status.ok = false;
+                        status.error = result.error;
+                    }
+                    statusById.set(result.source, status);
+                    task.stats.perQuery[query.id] =
+                        (task.stats.perQuery[query.id] ?? 0) + records.length;
+                    records.forEach((record, position) => {
+                        hits.push({
+                            record,
+                            source: result.source,
+                            rank: position + 1,
+                            queryId: query.id,
+                        });
+                    });
+                }
+            }
+            const merged = mergeHits(hits);
+            const papers = merged
+                .filter((paper) => matchesConditions(paper, task.conditions))
+                .slice(0, getSettings().taskMaxPapers);
+            task.result.papers = papers;
+            task.result.sources = [...statusById.values()];
+            task.result.fetchedAt = new Date().toISOString();
+            task.stats.rawHits = hits.length;
+            task.stats.deduped = merged.length;
+            task.stats.screening = countScreening(papers, task.states);
+            const failed = task.result.sources.filter((source) => !source.ok && !source.skipped);
+            const succeeded = task.result.sources.filter((source) => source.ok && !source.skipped);
+            const skipped = task.result.sources.filter((source) => source.skipped);
+            // 全被限流跳过且结果为空时仍标 partial 提示重跑，但不显示任何红色失败。
+            task.status =
+                succeeded.length === 0 && failed.length > 0
+                    ? 'error'
+                    : failed.length > 0 || (succeeded.length === 0 && skipped.length > 0)
+                        ? 'partial'
+                        : 'done';
+            task.progress = undefined;
+        }
+        catch (error) {
+            if (controller.signal.aborted || error instanceof RunCanceled) {
+                task.status = 'canceled';
+                task.error = '检索已取消';
+            }
+            else {
+                task.status = 'error';
+                task.error = error instanceof Error ? error.message : String(error);
+            }
+            task.result.sources = [...statusById.values()];
+            task.stats.screening = countScreening(task.result.papers, task.states);
+            task.progress = undefined;
+        }
+        finally {
+            // 无论成功 / 取消 / 异常都回填本轮元数据，时间轴不会留下「永远运行中」的轮次。
+            finishRound(round, task);
+            touch(task, hooks);
+            await hooks.persist(task);
+        }
+    }
+}
+function touch(task, hooks) {
+    task.rev += 1;
+    task.updatedAt = new Date().toISOString();
+    hooks.publish(task);
+}
+/** 每个源多取一些给跨源/跨式去重留余量，但不放大到打爆上游。 */
+function clampRequestLimit(pageSize) {
+    const base = Number.isFinite(pageSize) ? pageSize : 20;
+    return Math.min(Math.max(Math.floor(base) * 2, 10), MAX_LIMIT);
+}
+function matchesConditions(paper, conditions) {
+    if (conditions.yearFrom !== undefined && (paper.year ?? 0) < conditions.yearFrom)
+        return false;
+    if (conditions.yearTo !== undefined &&
+        (paper.year ?? Number.MAX_SAFE_INTEGER) > conditions.yearTo) {
+        return false;
+    }
+    if (conditions.openAccessOnly && !paper.openAccess)
+        return false;
+    if (!matchesLanguage(paper, conditions.language))
+        return false;
+    if (conditions.types !== undefined && conditions.types.length > 0) {
+        const type = paper.type.toLowerCase();
+        if (!conditions.types.some((wanted) => wanted.toLowerCase() === type))
+            return false;
+    }
+    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');
+}