dsh-plugin-litsearch 0.3.5 → 0.4.0

package/lib/host/events.d.ts

@@ -5,15 +5,23 @@
  * 的 globalRev」日志；客户端按 `sinceRev` 轮询拿增量。globalRev 只在宿主进程内
  * 单调递增，重启后归零 —— 客户端发现 `sinceRev` 比服务端大就以 `reset` 重新同步。
  */
-import type { EventsPage, TaskSummary } from '../search/types.js';
+import type { DownloadCommand, EventsPage, TaskSummary, ZoteroCommand } from '../search/types.js';
 export declare class TaskEvents {
     private rev;
     private readonly entries;
     private focus;
+    /** 下载指令日志：数组而非单值，两次轮询之间连发多条也不会互相覆盖。 */
+    private readonly downloadEntries;
+    /** Zotero 同步指令日志，与下载并列，互不覆盖。 */
+    private readonly zoteroEntries;
     get currentRev(): number;
     publish(summary: TaskSummary): void;
     /** 请求客户端把某个任务 tab 打开/切到前台（面板关着时重新打开）。 */
     requestFocus(taskId: string, title: string, sessionId?: string): void;
+    /** 下发一条模型批量下载指令；与 focus 一样推进 globalRev 走增量轮询。 */
+    publishDownload(command: DownloadCommand): void;
+    /** 下发一条模型 Zotero 同步指令；与下载指令一样推进 globalRev 走增量轮询。 */
+    publishZotero(command: ZoteroCommand): void;
     remove(id: string): void;
     since(sinceRev: number): EventsPage;
 }

package/lib/host/events.js

@@ -5,10 +5,17 @@
  * 的 globalRev」日志；客户端按 `sinceRev` 轮询拿增量。globalRev 只在宿主进程内
  * 单调递增，重启后归零 —— 客户端发现 `sinceRev` 比服务端大就以 `reset` 重新同步。
  */
+/** 事件日志里最多保留多少条模型指令，避免长时间运行无限增长。 */
+const MAX_DOWNLOAD_ENTRIES = 50;
+const MAX_ZOTERO_ENTRIES = 50;
 export class TaskEvents {
     rev = 0;
     entries = new Map();
     focus;
+    /** 下载指令日志：数组而非单值，两次轮询之间连发多条也不会互相覆盖。 */
+    downloadEntries = [];
+    /** Zotero 同步指令日志，与下载并列，互不覆盖。 */
+    zoteroEntries = [];
     get currentRev() {
         return this.rev;
     }
@@ -27,17 +34,42 @@ export class TaskEvents {
             ...(sessionId === undefined ? {} : { sessionId }),
         };
     }
+    /** 下发一条模型批量下载指令；与 focus 一样推进 globalRev 走增量轮询。 */
+    publishDownload(command) {
+        this.rev += 1;
+        this.downloadEntries.push({ globalRev: this.rev, command });
+        if (this.downloadEntries.length > MAX_DOWNLOAD_ENTRIES) {
+            this.downloadEntries.splice(0, this.downloadEntries.length - MAX_DOWNLOAD_ENTRIES);
+        }
+    }
+    /** 下发一条模型 Zotero 同步指令；与下载指令一样推进 globalRev 走增量轮询。 */
+    publishZotero(command) {
+        this.rev += 1;
+        this.zoteroEntries.push({ globalRev: this.rev, command });
+        if (this.zoteroEntries.length > MAX_ZOTERO_ENTRIES) {
+            this.zoteroEntries.splice(0, this.zoteroEntries.length - MAX_ZOTERO_ENTRIES);
+        }
+    }
     remove(id) {
         this.entries.delete(id);
         if (this.focus?.taskId === id)
             this.focus = undefined;
+        for (let index = this.downloadEntries.length - 1; index >= 0; index -= 1) {
+            if (this.downloadEntries[index]?.command.taskId === id)
+                this.downloadEntries.splice(index, 1);
+        }
+        for (let index = this.zoteroEntries.length - 1; index >= 0; index -= 1) {
+            if (this.zoteroEntries[index]?.command.taskId === id)
+                this.zoteroEntries.splice(index, 1);
+        }
     }
     since(sinceRev) {
         if (!Number.isFinite(sinceRev) || sinceRev < 0) {
-            return { rev: this.rev, reset: true, tasks: [] };
+            // 宿主重启 / 客户端状态错乱：重新对齐，不重放历史模型指令。
+            return { rev: this.rev, reset: true, tasks: [], downloads: [], zotero: [] };
         }
         if (sinceRev > this.rev) {
-            return { rev: this.rev, reset: true, tasks: [] };
+            return { rev: this.rev, reset: true, tasks: [], downloads: [], zotero: [] };
         }
         const tasks = [...this.entries.values()]
             .filter((entry) => entry.globalRev > sinceRev)
@@ -53,6 +85,21 @@ export class TaskEvents {
                     : { sessionId: this.focus.sessionId }),
             }
             : undefined;
-        return { rev: this.rev, reset: false, tasks, ...(focus === undefined ? {} : { focus }) };
+        const downloads = this.downloadEntries
+            .filter((entry) => entry.globalRev > sinceRev)
+            .sort((a, b) => a.globalRev - b.globalRev)
+            .map((entry) => entry.command);
+        const zotero = this.zoteroEntries
+            .filter((entry) => entry.globalRev > sinceRev)
+            .sort((a, b) => a.globalRev - b.globalRev)
+            .map((entry) => entry.command);
+        return {
+            rev: this.rev,
+            reset: false,
+            tasks,
+            ...(focus === undefined ? {} : { focus }),
+            downloads,
+            zotero,
+        };
     }
 }

package/lib/host/router.js

@@ -247,6 +247,45 @@ function readStringArray(value, name, maxItems, maxLength) {
     }
     return value.map((item) => item.trim().slice(0, maxLength)).filter((item) => item !== '');
 }
+/**
+ * 解析客户端上报的当前视图快照。
+ *
+ * 只按白名单取值，未知字段 / 非基本类型一律丢弃；会话 id 由请求头决定，
+ * 时间由 Host 重置，避免客户端伪造别的会话或让快照永不过期。
+ */
+function readViewSnapshot(body, sessionId) {
+    const taskId = readString(body['taskId'], 'taskId', 200) ?? '';
+    if (taskId === '')
+        throw new SearchError('bad_request', '缺少 taskId');
+    const filters = {};
+    const rawFilters = body['filters'];
+    if (rawFilters !== null && typeof rawFilters === 'object' && !Array.isArray(rawFilters)) {
+        for (const [key, value] of Object.entries(asRecord(rawFilters))) {
+            const name = key.slice(0, 60);
+            if (typeof value === 'string' && value.length <= 200)
+                filters[name] = value;
+            else if (typeof value === 'number' && Number.isFinite(value))
+                filters[name] = value;
+            else if (typeof value === 'boolean')
+                filters[name] = value;
+        }
+    }
+    const sort = readEnum(body['sort'], 'sort', SORT_MODES);
+    const total = readInt(body['total'], 'total', 0, 1_000_000);
+    return {
+        sessionId,
+        taskId,
+        at: Date.now(),
+        pageIndex: readInt(body['pageIndex'], 'pageIndex', 0, 1_000_000) ?? 0,
+        pageSize: readInt(body['pageSize'], 'pageSize', 1, 200) ?? 20,
+        ...(total === undefined ? {} : { total }),
+        ...(sort === undefined ? {} : { sort }),
+        filters,
+        pagePaperIds: readStringArray(body['pagePaperIds'], 'pagePaperIds', 200, 200) ?? [],
+        selectedIds: readStringArray(body['selectedIds'], 'selectedIds', 1500, 200) ?? [],
+        rev: readInt(body['rev'], 'rev', 0, 1_000_000_000) ?? 0,
+    };
+}
 function readQueriesValue(value) {
     if (value === undefined || value === null)
         return undefined;
@@ -703,7 +742,17 @@ async function handleTasks(service, req, res, seg, params, sessionId) {
         }
         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, await resolveSessionWorkspace(sessionId)));
+        const targetId = readString(body['target'], 'target', 40);
+        const targetName = readString(body['targetName'], 'targetName', 200);
+        const targetFilesEditable = body['targetFilesEditable'];
+        const target = targetId === undefined || targetId === ''
+            ? undefined
+            : {
+                id: targetId,
+                ...(targetName === undefined || targetName === '' ? {} : { name: targetName }),
+                ...(typeof targetFilesEditable === 'boolean' ? { filesEditable: targetFilesEditable } : {}),
+            };
+        ok(res, await service.zoteroSync(id, ids === undefined || ids === null ? undefined : ids, await resolveSessionWorkspace(sessionId), target));
         return;
     }
     if (action === 'compare') {
@@ -784,6 +833,18 @@ export function createHandler(service) {
                 ok(res, await service.eventsSince(Number.isFinite(sinceRev) ? sinceRev : 0));
                 return;
             }
+            if (head === 'view') {
+                if (req.method !== 'POST') {
+                    fail(res, 405, 'bad_request', 'view 仅支持 POST');
+                    return;
+                }
+                const sessionId = readSessionId(req, url.searchParams);
+                if (sessionId === undefined)
+                    throw new SearchError('bad_request', '缺少会话 id');
+                service.saveViewSnapshot(sessionId, readViewSnapshot(await readJsonBody(req), sessionId));
+                ok(res, { saved: true });
+                return;
+            }
             if (head === 'files') {
                 if (seg[1] !== 'reveal') {
                     fail(res, 404, 'not_found', `未知文件操作 ${seg[1] ?? ''}`);
@@ -818,6 +879,10 @@ export function createHandler(service) {
                     ok(res, await service.cleanup(scope));
                     return;
                 }
+                if (seg[1] === 'zotero' && seg[2] === 'targets' && req.method === 'POST') {
+                    ok(res, await service.zoteroTargets());
+                    return;
+                }
                 if (seg[1] === 'zotero' && req.method === 'POST') {
                     ok(res, await service.zoteroProbe());
                     return;

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

@@ -0,0 +1,104 @@
+/**
+ * 模型下载指令的范围解析（纯函数，便于单测）。
+ *
+ * 模型跑在 Host 侧，看不到右侧栏翻到第几页、用了什么筛选。范围统一由视图
+ * 快照 + 服务端 `filterPapers` 算准，并逐个与任务结果取交集，最终只把一份
+ * 「已校验的 paperId 清单」交给 Client —— 浏览器不再解析任何条件，也不会
+ * 出现「模型理解的筛选」与「界面筛选」两套口径。
+ */
+import type { DownloadCommandItem, DownloadScope, PageBase, Paper, SearchTask, ViewSnapshot } from '../../search/types.js';
+import type { PaperFilter } from './filter.js';
+/**
+ * 把视图快照的扁平筛选投影收窄回 `PaperFilter`。
+ *
+ * 快照来自 Client 的 `ResultsQuery`，键名与筛选口径一致；这里只按白名单取，
+ * 未知键与非法枚举值一律忽略，避免模型/前端写入任意字段影响后台过滤。
+ */
+export declare function toPaperFilter(raw: ViewSnapshot['filters']): PaperFilter;
+/** 视图筛选打底，工具显式字段覆盖同名项；显式值为 undefined 的不覆盖。 */
+export declare function mergeDownloadFilter(base: PaperFilter, explicit: PaperFilter): PaperFilter;
+export interface ResolveDownloadOptions {
+    scope: DownloadScope;
+    /** 已经合并好的筛选条件（视图筛选 + 工具显式条件），用于范围说明。 */
+    filter: PaperFilter;
+    /**
+     * 调用方用 `filterPapers(task, filter)` 得到的论文集合。
+     *
+     * 本文件刻意不引入运行时模块依赖，筛选只在一处发生，避免模型下载与
+     * 界面结果出现两套口径；全量范围也不受 `/results` 的 200 条分页限制。
+     */
+    matched: readonly Paper[];
+    /** `scope='ids'` 时模型给出的显式清单。 */
+    explicitIds?: readonly string[];
+    /** 视图快照；`currentPage` / `currentView` / `pages` 需要它。 */
+    snapshot?: ViewSnapshot;
+    /** 快照过期时由服务层重算的当前页 paperId（保持用户所见顺序）。 */
+    pagePaperIds?: readonly string[];
+    /** `scope='pages'` 时模型给的 1-based 页码。 */
+    pages?: readonly number[];
+    /** 页码基准，默认 `view`（先切页再套附加条件）。 */
+    pageBase?: PageBase;
+    /**
+     * `pageBase='view'` 时切页用的集合：只含视图筛选、**不含**工具附加条件。
+     *
+     * 缺省回落到 `matched`（即先筛后切页），与 `pageBase='filtered'` 等价。
+     * 与 `matched` 一样，需由调用方按界面排序排好后再传入。
+     */
+    viewMatched?: readonly Paper[];
+    /** 每页篇数；缺省取客户端上报值。 */
+    pageSize?: number;
+    /** 分组名，仅用于范围说明。 */
+    groupName?: string;
+}
+export interface DownloadScopeResult {
+    paperIds: string[];
+    items: DownloadCommandItem[];
+    /** 清单里不属于该任务或不满足条件的 id 数。 */
+    ignored: number;
+    scopeLabel: string;
+    /** `scope='pages'` 时按当前每页篇数算出的总页数。 */
+    pageCount?: number;
+    /** 请求但超出总页数的页码（1-based）；非空时调用方应拒绝下发。 */
+    outOfRange?: number[];
+}
+export interface PageWindowOptions {
+    pages: readonly number[];
+    pageBase: PageBase;
+    /** `pageBase='filtered'` 的基础集合（筛选已全部合并）。 */
+    matched: readonly Paper[];
+    /** `pageBase='view'` 的基础集合（只含视图筛选）。 */
+    viewMatched: readonly Paper[];
+    /** 每页篇数；缺省用 `FALLBACK_PAGE_SIZE`。 */
+    pageSize?: number;
+}
+export interface PageWindowResult {
+    /** 页窗口内按页序（跨页不重复）展开的 paperId。 */
+    paperIds: string[];
+    pageSize: number;
+    pageCount: number;
+    outOfRange: number[];
+}
+/**
+ * 把「第 4–5 页」解析成 paperId 清单。
+ *
+ * 页码语义固定在「用户屏幕上那一页」：每页 `pageSize` 条（面板恒为 20）。
+ * **前置条件**：`matched` / `viewMatched` 必须已按界面排序排好（调用方用
+ * `filter.sortPapers`），否则切出来的页与面板不一致。
+ *
+ * `pageBase='view'` 时先切页、再与附加条件取交集，这样「第二页里有 PDF 的
+ * 文献」不会因为加了 `hasPdf` 而把页面整体前移。
+ */
+export declare function resolvePageWindow(options: PageWindowOptions): PageWindowResult;
+/**
+ * 解析范围 → 已校验的 paperId 清单。
+ *
+ * `ids` 按模型给定顺序、`currentPage` 按用户当前页顺序，其余按任务结果原序；
+ * 每种范围都会再与 `filterPapers` 的结果取交集，因此叠加 `hasPdf`、年份等
+ * 条件时与界面口径完全一致。全量直接用纯函数过滤，不受 `/results` 的 200
+ * 条分页上限约束。
+ */
+export declare function resolveDownloadScope(task: SearchTask, options: ResolveDownloadOptions): DownloadScopeResult;
+/** 生成给弹窗展示的中文范围说明（含篇数）；Client 只显示、不翻译、不再解析。 */
+export declare function buildScopeLabel(scope: DownloadScope, count: number, options: Pick<ResolveDownloadOptions, 'filter' | 'snapshot' | 'groupName' | 'pages'>): string;
+/** 页码列表 → 可读文案：`[2]` → `2`，`[4,5,6]` → `4–6`，`[2,5]` → `2、5`。 */
+export declare function describePages(pages: readonly number[]): string;

package/lib/host/tasks/download.js

@@ -0,0 +1,274 @@
+/**
+ * 模型下载指令的范围解析（纯函数，便于单测）。
+ *
+ * 模型跑在 Host 侧，看不到右侧栏翻到第几页、用了什么筛选。范围统一由视图
+ * 快照 + 服务端 `filterPapers` 算准，并逐个与任务结果取交集，最终只把一份
+ * 「已校验的 paperId 清单」交给 Client —— 浏览器不再解析任何条件，也不会
+ * 出现「模型理解的筛选」与「界面筛选」两套口径。
+ */
+/**
+ * 每页篇数的兜底值，与 `types.ts` 的 `RESULT_PAGE_SIZE`（面板分页粒度）一致。
+ *
+ * 本文件要能被 `node --test` 直接加载，因此不做任何运行时模块导入（`.js`
+ * 后缀在同环境里无法回落到 `.ts`）；真正的每页条数总由调用方通过视图快照
+ * 传入，这里只兜底。`test/download-scope.test.ts` 会断言它仍是 20。
+ */
+const FALLBACK_PAGE_SIZE = 20;
+/**
+ * 与 `types.ts` 的 `TASK_LANGUAGES` 一致。这里刻意只做类型导入、不产生运行时
+ * 模块依赖：`src` 源码可被 `node --test` 直接加载，Host 构建产物仍走 `.js`。
+ */
+const LANGUAGE_VALUES = [
+    'any',
+    'eng',
+    'chi',
+    'jpn',
+    'kor',
+    'fre',
+    'ger',
+    'spa',
+    'rus',
+    'ita',
+    'por',
+];
+const SCREENING_VALUES = ['unread', 'read', 'included', 'excluded'];
+const PDF_STATUS_VALUES = [
+    'unknown',
+    'available',
+    'downloaded',
+    'missing',
+    'html-only',
+    'paywalled',
+    'blocked',
+    'failed',
+];
+/**
+ * 把视图快照的扁平筛选投影收窄回 `PaperFilter`。
+ *
+ * 快照来自 Client 的 `ResultsQuery`，键名与筛选口径一致；这里只按白名单取，
+ * 未知键与非法枚举值一律忽略，避免模型/前端写入任意字段影响后台过滤。
+ */
+export function toPaperFilter(raw) {
+    const text = (key) => {
+        const value = raw[key];
+        return typeof value === 'string' && value !== '' ? value : undefined;
+    };
+    const number = (key) => {
+        const value = raw[key];
+        return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+    };
+    const flag = (key) => (raw[key] === true ? true : undefined);
+    const oneOf = (key, values) => {
+        const value = raw[key];
+        return typeof value === 'string' ? values.find((item) => item === value) : undefined;
+    };
+    return {
+        source: text('source'),
+        q: text('q'),
+        queryId: text('queryId'),
+        type: text('type'),
+        venue: text('venue'),
+        author: text('author'),
+        groupId: text('groupId'),
+        yearFrom: number('yearFrom'),
+        yearTo: number('yearTo'),
+        openAccessOnly: flag('openAccessOnly'),
+        hasPdf: flag('hasPdf'),
+        missingFullText: flag('missingFullText'),
+        newOnly: flag('newOnly'),
+        screening: oneOf('screening', SCREENING_VALUES),
+        language: oneOf('language', LANGUAGE_VALUES),
+        pdfStatus: oneOf('pdfStatus', PDF_STATUS_VALUES),
+    };
+}
+/** 视图筛选打底，工具显式字段覆盖同名项；显式值为 undefined 的不覆盖。 */
+export function mergeDownloadFilter(base, explicit) {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(explicit)) {
+        if (value === undefined)
+            continue;
+        Object.assign(merged, { [key]: value });
+    }
+    return merged;
+}
+/**
+ * 把「第 4–5 页」解析成 paperId 清单。
+ *
+ * 页码语义固定在「用户屏幕上那一页」：每页 `pageSize` 条（面板恒为 20）。
+ * **前置条件**：`matched` / `viewMatched` 必须已按界面排序排好（调用方用
+ * `filter.sortPapers`），否则切出来的页与面板不一致。
+ *
+ * `pageBase='view'` 时先切页、再与附加条件取交集，这样「第二页里有 PDF 的
+ * 文献」不会因为加了 `hasPdf` 而把页面整体前移。
+ */
+export function resolvePageWindow(options) {
+    const pageSize = Math.max(1, Math.floor(options.pageSize ?? FALLBACK_PAGE_SIZE));
+    const base = options.pageBase === 'view' ? options.viewMatched : options.matched;
+    const pageCount = Math.max(1, Math.ceil(base.length / pageSize));
+    const outOfRange = [];
+    const seen = new Set();
+    const paperIds = [];
+    for (const page of [...options.pages].sort((a, b) => a - b)) {
+        const index = Math.floor(page) - 1;
+        if (index < 0 || page > pageCount) {
+            outOfRange.push(page);
+            continue;
+        }
+        const start = index * pageSize;
+        for (const paper of base.slice(start, start + pageSize)) {
+            if (seen.has(paper.paperId))
+                continue;
+            seen.add(paper.paperId);
+            paperIds.push(paper.paperId);
+        }
+    }
+    return { paperIds, pageSize, pageCount, outOfRange };
+}
+/**
+ * 解析范围 → 已校验的 paperId 清单。
+ *
+ * `ids` 按模型给定顺序、`currentPage` 按用户当前页顺序，其余按任务结果原序；
+ * 每种范围都会再与 `filterPapers` 的结果取交集，因此叠加 `hasPdf`、年份等
+ * 条件时与界面口径完全一致。全量直接用纯函数过滤，不受 `/results` 的 200
+ * 条分页上限约束。
+ */
+export function resolveDownloadScope(task, options) {
+    const byId = new Map(task.result.papers.map((paper) => [paper.paperId, paper]));
+    const eligible = new Set(options.matched.map((paper) => paper.paperId));
+    let ordered;
+    let pageCount;
+    let outOfRange;
+    switch (options.scope) {
+        case 'ids': {
+            const seen = new Set();
+            ordered = [];
+            for (const raw of options.explicitIds ?? []) {
+                const id = raw.trim();
+                if (id === '' || seen.has(id))
+                    continue;
+                seen.add(id);
+                ordered.push(id);
+            }
+            break;
+        }
+        case 'currentPage': {
+            ordered = [...(options.pagePaperIds ?? options.snapshot?.pagePaperIds ?? [])];
+            break;
+        }
+        case 'pages': {
+            const window = resolvePageWindow({
+                pages: options.pages ?? [],
+                pageBase: options.pageBase ?? 'view',
+                matched: options.matched,
+                viewMatched: options.viewMatched ?? options.matched,
+                ...(options.pageSize === undefined ? {} : { pageSize: options.pageSize }),
+            });
+            ordered = window.paperIds;
+            pageCount = window.pageCount;
+            outOfRange = window.outOfRange;
+            break;
+        }
+        default: {
+            ordered = options.matched.map((paper) => paper.paperId);
+            break;
+        }
+    }
+    const paperIds = [];
+    const items = [];
+    for (const id of ordered) {
+        if (!eligible.has(id))
+            continue;
+        const paper = byId.get(id);
+        if (paper === undefined)
+            continue;
+        paperIds.push(id);
+        const meta = [paper.venue, paper.year === null ? '' : String(paper.year)]
+            .filter((part) => part !== '')
+            .join(' · ');
+        items.push({
+            paperId: id,
+            title: paper.title,
+            source: paper.hitSources[0]?.source ?? paper.source,
+            ...(meta === '' ? {} : { meta }),
+        });
+    }
+    return {
+        paperIds,
+        items,
+        ignored: ordered.length - paperIds.length,
+        scopeLabel: buildScopeLabel(options.scope, paperIds.length, options),
+        ...(pageCount === undefined ? {} : { pageCount }),
+        ...(outOfRange === undefined ? {} : { outOfRange }),
+    };
+}
+/** 生成给弹窗展示的中文范围说明（含篇数）；Client 只显示、不翻译、不再解析。 */
+export function buildScopeLabel(scope, count, options) {
+    const parts = [];
+    switch (scope) {
+        case 'ids':
+            parts.push('指定文献');
+            break;
+        case 'currentPage':
+            parts.push(`当前页（第 ${(options.snapshot?.pageIndex ?? 0) + 1} 页）`);
+            break;
+        case 'pages':
+            parts.push(`第 ${describePages(options.pages ?? [])} 页`);
+            break;
+        case 'currentView':
+            parts.push('当前筛选全部');
+            break;
+        case 'all':
+            parts.push('整个任务全部文献');
+            break;
+        case 'group':
+            parts.push(`分组「${options.groupName ?? options.filter.groupId ?? ''}」`);
+            break;
+        case 'filters':
+            parts.push('按条件筛选');
+            break;
+    }
+    const filter = options.filter;
+    if (filter.hasPdf === true)
+        parts.push('仅含 PDF 直链或已下载');
+    if (filter.openAccessOnly === true)
+        parts.push('仅开放获取');
+    if (filter.q !== undefined && filter.q !== '')
+        parts.push(`关键词「${filter.q}」`);
+    if (filter.groupId !== undefined && scope !== 'group')
+        parts.push(`分组 ${filter.groupId}`);
+    if (filter.yearFrom !== undefined || filter.yearTo !== undefined) {
+        parts.push(`${filter.yearFrom ?? '不限'}–${filter.yearTo ?? '不限'} 年`);
+    }
+    if (filter.source !== undefined)
+        parts.push(`来源 ${filter.source}`);
+    if (filter.screening !== undefined)
+        parts.push(`筛读 ${filter.screening}`);
+    if (filter.pdfStatus !== undefined)
+        parts.push(`全文状态 ${filter.pdfStatus}`);
+    if (filter.venue !== undefined && filter.venue !== '')
+        parts.push(`出处 ${filter.venue}`);
+    if (filter.author !== undefined && filter.author !== '')
+        parts.push(`作者 ${filter.author}`);
+    return `${parts.join(' · ')} · 共 ${count} 篇`;
+}
+/** 页码列表 → 可读文案：`[2]` → `2`，`[4,5,6]` → `4–6`，`[2,5]` → `2、5`。 */
+export function describePages(pages) {
+    const sorted = [...new Set(pages)].sort((a, b) => a - b);
+    if (sorted.length === 0)
+        return '';
+    const chunks = [];
+    let start = sorted[0];
+    let prev = sorted[0];
+    for (let index = 1; index < sorted.length; index += 1) {
+        const page = sorted[index];
+        if (page === prev + 1) {
+            prev = page;
+            continue;
+        }
+        chunks.push(start === prev ? String(start) : `${start}–${prev}`);
+        start = page;
+        prev = page;
+    }
+    chunks.push(start === prev ? String(start) : `${start}–${prev}`);
+    return chunks.join('、');
+}

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

@@ -3,7 +3,7 @@
  *
  * 任何新筛选条件都必须先加到这里，避免列表与统计出现两套过滤逻辑。
  */
-import type { Paper, PdfStatus, Screening, SearchTask, TaskLanguage } from '../../search/types.js';
+import type { Paper, PdfStatus, Screening, SearchTask, SortMode, TaskLanguage } from '../../search/types.js';
 export interface PaperFilter {
     source?: string;
     yearFrom?: number;
@@ -35,6 +35,13 @@ export interface PaperFilter {
 }
 export declare function filterPapers(task: SearchTask, filter?: PaperFilter): Paper[];
 export declare function screeningOf(task: SearchTask, paper: Paper): Screening;
+/**
+ * 结果排序：`/results`、`/stats` 与模型侧的按页取数共用这一份口径。
+ *
+ * `relevance` 保持上游合并后的原序（不做二次排序）；被引/年份缺失的排在最后，
+ * 与面板看到的顺序一致。原地排序，调用方传入副本。
+ */
+export declare function sortPapers(papers: Paper[], sort: SortMode | undefined): void;
 /** 有效全文状态：没有人工/下载记录时，上游给的 PDF 直链视为可用。 */
 export declare function pdfStatusOf(task: SearchTask, paper: Paper): PdfStatus;
 export declare function matchesLanguage(paper: {

package/lib/host/tasks/filter.js

@@ -62,6 +62,20 @@ export function filterPapers(task, filter = {}) {
 export function screeningOf(task, paper) {
     return task.states[paper.paperId]?.screening ?? 'unread';
 }
+/**
+ * 结果排序：`/results`、`/stats` 与模型侧的按页取数共用这一份口径。
+ *
+ * `relevance` 保持上游合并后的原序（不做二次排序）；被引/年份缺失的排在最后，
+ * 与面板看到的顺序一致。原地排序，调用方传入副本。
+ */
+export function sortPapers(papers, 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));
+    }
+}
 /** 有效全文状态：没有人工/下载记录时，上游给的 PDF 直链视为可用。 */
 export function pdfStatusOf(task, paper) {
     const recorded = task.states[paper.paperId]?.pdfStatus;