dsh-plugin-litsearch 0.3.0 → 0.4.0

package/lib/host/router.js

@@ -6,11 +6,15 @@
  * `sec-fetch-site: cross-site`。写端点额外要求自定义头 + JSON content-type，
  * 两者一起让浏览器必须预检，堵掉跨站表单与简单请求。
  */
+import { spawn } from 'node:child_process';
+import { mkdir, stat } from 'node:fs/promises';
+import { dirname, extname, isAbsolute, resolve } from 'node:path';
 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 { resolvePdfRoot } from './pdf/store.js';
 import { resolveSessionWorkspace } from './workspace.js';
 const MAX_BODY_BYTES = 1_000_000;
 const SORT_MODES = ['relevance', 'citations', 'year'];
@@ -21,6 +25,7 @@ const PDF_STATUSES = [
     'unknown',
     'available',
     'downloaded',
+    'missing',
     'html-only',
     'paywalled',
     'blocked',
@@ -81,48 +86,6 @@ function sendFile(res, file) {
     });
     res.end(body);
 }
-/** 内联 PDF，支持单段 Range（预览器会按需拉取）。 */
-function sendPdf(req, res, buffer, filename) {
-    const total = buffer.length;
-    const disposition = `inline; filename*=UTF-8''${encodeURIComponent(filename)}`;
-    const range = req.headers.range;
-    if (range === undefined) {
-        res.writeHead(200, {
-            'content-type': 'application/pdf',
-            'content-length': total,
-            'content-disposition': disposition,
-            'accept-ranges': 'bytes',
-            'cache-control': 'no-store',
-        });
-        res.end(buffer);
-        return;
-    }
-    const match = /^bytes=(\d*)-(\d*)$/u.exec(range.trim());
-    const start = match?.[1] === '' ? Number.NaN : Number(match?.[1]);
-    const end = match?.[2] === '' ? Number.NaN : Number(match?.[2]);
-    if (match === null || (!Number.isFinite(start) && !Number.isFinite(end))) {
-        res.writeHead(416, { 'content-range': `bytes */${total}`, 'cache-control': 'no-store' });
-        res.end();
-        return;
-    }
-    const from = Number.isFinite(start) ? Math.max(0, start) : Math.max(0, total - (end || 0));
-    const to = Number.isFinite(end) ? Math.min(end, total - 1) : total - 1;
-    if (from > to || from >= total) {
-        res.writeHead(416, { 'content-range': `bytes */${total}`, 'cache-control': 'no-store' });
-        res.end();
-        return;
-    }
-    const chunk = buffer.subarray(from, to + 1);
-    res.writeHead(206, {
-        'content-type': 'application/pdf',
-        'content-length': chunk.length,
-        'content-range': `bytes ${from}-${to}/${total}`,
-        'content-disposition': disposition,
-        'accept-ranges': 'bytes',
-        'cache-control': 'no-store',
-    });
-    res.end(chunk);
-}
 function sendHtml(res, status, html) {
     res.writeHead(status, {
         'content-type': 'text/html; charset=utf-8',
@@ -130,6 +93,52 @@ function sendHtml(res, status, html) {
     });
     res.end(html);
 }
+/**
+ * 在系统文件管理器中定位文件：macOS Finder、Windows 资源管理器、Linux 桌面。
+ * 只接受已存在的 PDF 文件或目录（批量下载的「打开下载目录」用后者），
+ * 避免这个端点被当成任意路径探测。
+ */
+async function revealInFileManager(rawPath, downloadRoot) {
+    const target = resolve(rawPath);
+    let info = await stat(target).catch(() => null);
+    // 下载目录可能一篇都还没下过：打开前补建，避免点「打开下载目录」毫无反应。
+    if (info === null && downloadRoot !== undefined && resolve(downloadRoot) === target) {
+        await mkdir(target, { recursive: true });
+        info = await stat(target).catch(() => null);
+    }
+    if (info === null)
+        throw new SearchError('not_found', '文件不存在或已被移动');
+    if (info.isDirectory()) {
+        const [command, args] = process.platform === 'darwin'
+            ? ['open', [target]]
+            : process.platform === 'win32'
+                ? ['explorer.exe', [target]]
+                : ['xdg-open', [target]];
+        await spawnDetached(command, args);
+        return { path: target };
+    }
+    if (!info.isFile() || extname(target).toLowerCase() !== '.pdf') {
+        throw new SearchError('bad_request', '只能定位 PDF 文件或下载目录');
+    }
+    const [command, args] = process.platform === 'darwin'
+        ? ['open', ['-R', target]]
+        : process.platform === 'win32'
+            ? ['explorer.exe', [`/select,${target}`]]
+            : ['xdg-open', [dirname(target)]];
+    await spawnDetached(command, args);
+    return { path: target };
+}
+/** 启动系统命令后立即脱离，不等待它的生命周期。 */
+async function spawnDetached(command, args) {
+    await new Promise((settle, rejectSpawn) => {
+        const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+        child.once('error', rejectSpawn);
+        child.once('spawn', () => {
+            child.unref();
+            settle();
+        });
+    });
+}
 function sendHtmlError(res, error) {
     const { status, error: apiError } = toApiError(error);
     sendHtml(res, status === 500 ? 502 : status, `<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><title>全文不可用</title></head><body style="font:14px/1.7 -apple-system,'PingFang SC',sans-serif;padding:16px"><p>全文不可用：${escapeHtml(apiError.message)}</p></body></html>`);
@@ -238,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;
@@ -300,26 +348,6 @@ function readAnnotations(value) {
             if (groupId !== undefined)
                 input.groupId = groupId;
         }
-        if (record['shortlistOrder'] === null)
-            input.shortlistOrder = null;
-        else if (record['shortlistOrder'] !== undefined) {
-            const order = readInt(record['shortlistOrder'], 'shortlistOrder', 0, 100_000);
-            if (order !== undefined)
-                input.shortlistOrder = order;
-        }
-        if (record['note'] !== undefined) {
-            if (typeof record['note'] !== 'string') {
-                throw new SearchError('bad_request', 'note 必须是字符串');
-            }
-            input.note = record['note'].slice(0, 4_000);
-        }
-        if (record['tags'] !== undefined) {
-            const tags = readStringArray(record['tags'], 'tags', 20, 40);
-            if (tags !== undefined && tags !== null)
-                input.tags = tags;
-            else if (tags === null)
-                input.tags = [];
-        }
         return input;
     });
 }
@@ -590,7 +618,7 @@ async function handleTasks(service, req, res, seg, params, sessionId) {
     const action = seg[2];
     if (action === undefined) {
         if (req.method === 'GET') {
-            ok(res, await service.getDetail(id));
+            ok(res, await service.getDetail(id, await resolveSessionWorkspace(sessionId)));
             return;
         }
         if (req.method === 'PATCH') {
@@ -664,7 +692,7 @@ async function handleTasks(service, req, res, seg, params, sessionId) {
                 fail(res, 405, 'bad_request', '论文详情仅支持 GET');
                 return;
             }
-            ok(res, await service.paperDetail(id, paperId));
+            ok(res, await service.paperDetail(id, paperId, await resolveSessionWorkspace(sessionId)));
             return;
         }
         if (op === 'entities') {
@@ -675,27 +703,20 @@ async function handleTasks(service, req, res, seg, params, sessionId) {
             ok(res, await service.entities(id, paperId));
             return;
         }
-        if (op === 'download') {
+        if (op === 'recheck') {
             if (req.method !== 'POST') {
-                fail(res, 405, 'bad_request', 'download 仅支持 POST');
+                fail(res, 405, 'bad_request', 'recheck 仅支持 POST');
                 return;
             }
-            ok(res, await service.downloadPdf(id, paperId, await resolveSessionWorkspace(sessionId)));
+            ok(res, await service.recheckPdf(id, paperId));
             return;
         }
-        if (op === 'pdf') {
-            if (req.method !== 'GET') {
-                fail(res, 405, 'bad_request', 'pdf 仅支持 GET');
+        if (op === 'download') {
+            if (req.method !== 'POST') {
+                fail(res, 405, 'bad_request', 'download 仅支持 POST');
                 return;
             }
-            try {
-                const file = await service.previewPdf(id, paperId, await resolveSessionWorkspace(sessionId));
-                sendPdf(req, res, file.buffer, file.filename);
-            }
-            catch (error) {
-                const { status, error: apiError } = toApiError(error);
-                fail(res, status === 500 ? 502 : status, apiError.code, apiError.message);
-            }
+            ok(res, await service.downloadPdf(id, paperId, await resolveSessionWorkspace(sessionId)));
             return;
         }
         if (op === 'fulltext') {
@@ -721,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') {
@@ -802,6 +833,38 @@ 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] ?? ''}`);
+                    return;
+                }
+                if (req.method !== 'POST') {
+                    fail(res, 405, 'bad_request', 'reveal 仅支持 POST');
+                    return;
+                }
+                const body = await readJsonBody(req);
+                const path = readString(body['path'], 'path', 4096);
+                if (path === undefined || path === '') {
+                    throw new SearchError('bad_request', '缺少 path 参数');
+                }
+                if (!isAbsolute(path))
+                    throw new SearchError('bad_request', 'path 必须是绝对路径');
+                const workspace = await resolveSessionWorkspace(readSessionId(req, url.searchParams));
+                ok(res, await revealInFileManager(path, resolvePdfRoot(workspace)));
+                return;
+            }
             if (head === 'settings') {
                 if (seg[1] === 'probe' && req.method === 'POST') {
                     const source = readString((await readJsonBody(req))['source'], 'source', 40);
@@ -816,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;