dsh-plugin-litsearch 0.0.0-stage → 0.2.0

package/lib/search/config.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 检索层常量与运行时设置。
+ *
+ * 设置由插件入口在 `apply` 时注入，读取时逐次走 volatile 引用，因此设置中心
+ * 保存配置后无需重启即生效。
+ */
+import type { SortMode, SourceId, TaskLanguage } from './types.js';
+/** 插件版本（与 package.json 同步；仅用于 /health 诊断展示）。 */
+export declare const PLUGIN_VERSION = "0.1.0";
+/** 默认每次加载条数。 */
+export declare const DEFAULT_PAGE_SIZE = 20;
+/**
+ * 单次上游请求超时（毫秒）。
+ *
+ * Europe PMC 的 `resultType=core` 明显慢于其它源，15s 容易误判为失败；
+ * 这里给全局一个更宽裕的默认值，检索层仍对该源单独设下限。
+ */
+export declare const REQUEST_TIMEOUT_MS = 20000;
+/** 返回条数上限，防止一次请求拉爆上游与宿主。 */
+export declare const MAX_LIMIT = 50;
+/** 默认排序。 */
+export declare const DEFAULT_SORT: SortMode;
+/** 默认语言筛选。 */
+export declare const DEFAULT_LANGUAGE: TaskLanguage;
+/** 模型发起检索时默认自动打开任务 tab。 */
+export declare const DEFAULT_AUTO_OPEN = true;
+/** 同时保留的任务 tab 上限。 */
+export declare const DEFAULT_MAX_TASK_TABS = 5;
+/** 任务保留天数与条数。 */
+export declare const DEFAULT_RETENTION_DAYS = 90;
+export declare const DEFAULT_RETENTION_COUNT = 120;
+/** 单任务结果上限。 */
+export declare const DEFAULT_TASK_MAX_PAPERS = 1500;
+/** 单任务保留的检索轮数上限；只记元数据，超出后淘汰最旧的轮次。 */
+export declare const DEFAULT_TASK_MAX_ROUNDS = 30;
+/** 各源默认最小请求间隔（毫秒）；PubMed/S2/arXiv 可由设置覆盖。 */
+export declare const DEFAULT_PUBMED_INTERVAL_MS = 350;
+export declare const DEFAULT_S2_INTERVAL_MS = 3000;
+export declare const DEFAULT_ARXIV_INTERVAL_MS = 3000;
+/** 全文下载默认设置。 */
+export declare const DEFAULT_PDF_MAX_MB = 30;
+export declare const DEFAULT_AUTO_DOWNLOAD_PDF = false;
+export declare const DEFAULT_ENABLE_EPMC_FULLTEXT = true;
+/** Zotero connector 默认设置。 */
+export declare const DEFAULT_ZOTERO_ENABLED = true;
+export declare const DEFAULT_ZOTERO_BASE_URL = "http://127.0.0.1:23119";
+export declare const DEFAULT_ZOTERO_ATTACH_PDF = true;
+export declare const DEFAULT_ZOTERO_TAG = "dsh-litsearch";
+/** 持久化时单条摘要保留的字符数。 */
+export declare const MAX_ABSTRACT_CHARS = 800;
+/** 写端点的自定义请求头（与 JSON content-type 一起构成非简单请求）。 */
+export declare const WRITE_HEADER = "x-dsh-litsearch-write";
+/** Host 路由前缀（Client fetch 路径与 handler 的剥离基准，带尾斜杠）。 */
+export declare const ROUTE_PREFIX = "/dsh-litsearch/api/";
+/**
+ * 注册到 `webServer` 的 prefix 路径。
+ *
+ * 必须**不带尾斜杠**：宿主按 `pathname === prefix || pathname.startsWith(prefix + '/')`
+ * 匹配，带尾斜杠会变成 `.../api//tasks`，永远匹配不上。
+ */
+export declare const ROUTE_MATCH = "/dsh-litsearch/api";
+export interface LitsearchSettings {
+    /** 联系邮箱，作为 OpenAlex / Crossref polite pool 与 NCBI email 标识；留空也可用。 */
+    contactEmail: string;
+    defaultPageSize: number;
+    requestTimeoutMs: number;
+    defaultSources: SourceId[];
+    defaultSort: SortMode;
+    defaultLanguage: TaskLanguage;
+    autoOpenTaskTab: boolean;
+    maxTaskTabs: number;
+    taskRetentionDays: number;
+    taskRetentionCount: number;
+    taskMaxPapers: number;
+    /** 可选 NCBI API Key；有 key 时 E-utilities 额度更高。 */
+    ncbiApiKey: string;
+    /** 可选 Semantic Scholar API Key；提高配额。 */
+    s2ApiKey: string;
+    /** 各源最小请求间隔覆盖值。 */
+    pubmedIntervalMs: number;
+    s2IntervalMs: number;
+    arxivIntervalMs: number;
+    /** PDF 下载根目录；空串由 Host 回落到 ~/Downloads/dsh-litsearch。 */
+    pdfRoot: string;
+    pdfMaxMb: number;
+    autoDownloadPdf: boolean;
+    enableEpmcFulltext: boolean;
+    zoteroEnabled: boolean;
+    zoteroBaseUrl: string;
+    zoteroAttachPdf: boolean;
+    zoteroTag: string;
+}
+/** 由插件入口在 `apply` 时注入。 */
+export declare function setSettingsReader(reader: () => LitsearchSettings): void;
+/** 读取当前生效的设置。 */
+export declare function getSettings(): LitsearchSettings;

package/lib/search/config.js

@@ -0,0 +1,96 @@
+/**
+ * 检索层常量与运行时设置。
+ *
+ * 设置由插件入口在 `apply` 时注入，读取时逐次走 volatile 引用，因此设置中心
+ * 保存配置后无需重启即生效。
+ */
+import { SOURCE_IDS } from './types.js';
+/** 插件版本（与 package.json 同步；仅用于 /health 诊断展示）。 */
+export const PLUGIN_VERSION = '0.1.0';
+/** 默认每次加载条数。 */
+export const DEFAULT_PAGE_SIZE = 20;
+/**
+ * 单次上游请求超时（毫秒）。
+ *
+ * Europe PMC 的 `resultType=core` 明显慢于其它源，15s 容易误判为失败；
+ * 这里给全局一个更宽裕的默认值，检索层仍对该源单独设下限。
+ */
+export const REQUEST_TIMEOUT_MS = 20_000;
+/** 返回条数上限，防止一次请求拉爆上游与宿主。 */
+export const MAX_LIMIT = 50;
+/** 默认排序。 */
+export const DEFAULT_SORT = 'relevance';
+/** 默认语言筛选。 */
+export const DEFAULT_LANGUAGE = 'any';
+/** 模型发起检索时默认自动打开任务 tab。 */
+export const DEFAULT_AUTO_OPEN = true;
+/** 同时保留的任务 tab 上限。 */
+export const DEFAULT_MAX_TASK_TABS = 5;
+/** 任务保留天数与条数。 */
+export const DEFAULT_RETENTION_DAYS = 90;
+export const DEFAULT_RETENTION_COUNT = 120;
+/** 单任务结果上限。 */
+export const DEFAULT_TASK_MAX_PAPERS = 1500;
+/** 单任务保留的检索轮数上限；只记元数据，超出后淘汰最旧的轮次。 */
+export const DEFAULT_TASK_MAX_ROUNDS = 30;
+/** 各源默认最小请求间隔（毫秒）；PubMed/S2/arXiv 可由设置覆盖。 */
+export const DEFAULT_PUBMED_INTERVAL_MS = 350;
+export const DEFAULT_S2_INTERVAL_MS = 3000;
+export const DEFAULT_ARXIV_INTERVAL_MS = 3000;
+/** 全文下载默认设置。 */
+export const DEFAULT_PDF_MAX_MB = 30;
+export const DEFAULT_AUTO_DOWNLOAD_PDF = false;
+export const DEFAULT_ENABLE_EPMC_FULLTEXT = true;
+/** Zotero connector 默认设置。 */
+export const DEFAULT_ZOTERO_ENABLED = true;
+export const DEFAULT_ZOTERO_BASE_URL = 'http://127.0.0.1:23119';
+export const DEFAULT_ZOTERO_ATTACH_PDF = true;
+export const DEFAULT_ZOTERO_TAG = 'dsh-litsearch';
+/** 持久化时单条摘要保留的字符数。 */
+export const MAX_ABSTRACT_CHARS = 800;
+/** 写端点的自定义请求头（与 JSON content-type 一起构成非简单请求）。 */
+export const WRITE_HEADER = 'x-dsh-litsearch-write';
+/** Host 路由前缀（Client fetch 路径与 handler 的剥离基准，带尾斜杠）。 */
+export const ROUTE_PREFIX = '/dsh-litsearch/api/';
+/**
+ * 注册到 `webServer` 的 prefix 路径。
+ *
+ * 必须**不带尾斜杠**：宿主按 `pathname === prefix || pathname.startsWith(prefix + '/')`
+ * 匹配，带尾斜杠会变成 `.../api//tasks`，永远匹配不上。
+ */
+export const ROUTE_MATCH = '/dsh-litsearch/api';
+/** 默认读取器：入口未注入时回落到常量。 */
+let readSettings = () => ({
+    contactEmail: '',
+    defaultPageSize: DEFAULT_PAGE_SIZE,
+    requestTimeoutMs: REQUEST_TIMEOUT_MS,
+    defaultSources: [...SOURCE_IDS],
+    defaultSort: DEFAULT_SORT,
+    defaultLanguage: DEFAULT_LANGUAGE,
+    autoOpenTaskTab: DEFAULT_AUTO_OPEN,
+    maxTaskTabs: DEFAULT_MAX_TASK_TABS,
+    taskRetentionDays: DEFAULT_RETENTION_DAYS,
+    taskRetentionCount: DEFAULT_RETENTION_COUNT,
+    taskMaxPapers: DEFAULT_TASK_MAX_PAPERS,
+    ncbiApiKey: '',
+    s2ApiKey: '',
+    pubmedIntervalMs: DEFAULT_PUBMED_INTERVAL_MS,
+    s2IntervalMs: DEFAULT_S2_INTERVAL_MS,
+    arxivIntervalMs: DEFAULT_ARXIV_INTERVAL_MS,
+    pdfRoot: '',
+    pdfMaxMb: DEFAULT_PDF_MAX_MB,
+    autoDownloadPdf: DEFAULT_AUTO_DOWNLOAD_PDF,
+    enableEpmcFulltext: DEFAULT_ENABLE_EPMC_FULLTEXT,
+    zoteroEnabled: DEFAULT_ZOTERO_ENABLED,
+    zoteroBaseUrl: DEFAULT_ZOTERO_BASE_URL,
+    zoteroAttachPdf: DEFAULT_ZOTERO_ATTACH_PDF,
+    zoteroTag: DEFAULT_ZOTERO_TAG,
+});
+/** 由插件入口在 `apply` 时注入。 */
+export function setSettingsReader(reader) {
+    readSettings = reader;
+}
+/** 读取当前生效的设置。 */
+export function getSettings() {
+    return readSettings();
+}

package/lib/search/errors.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 检索错误：只区分调用方可处理的几类。
+ *
+ * - `bad_request`：参数不合法（关键词为空、年份区间倒置等）。
+ * - `not_found` / `conflict`：任务不存在、或与运行中/版本号冲突。
+ * - `upstream_error`：上游返回非 2xx 或响应不可解析。
+ * - `timeout` / `network_error`：请求超时或网络不可达。
+ *
+ * `status` / `retryAfterMs` 只用于限流判断，不进入对外错误信封。
+ */
+import type { ApiErrorCode } from './types.js';
+export type SearchErrorCode = Exclude<ApiErrorCode, 'internal_error'>;
+export interface SearchErrorExtra {
+    status?: number;
+    retryAfterMs?: number;
+}
+export declare class SearchError extends Error {
+    readonly code: SearchErrorCode;
+    readonly status?: number;
+    readonly retryAfterMs?: number;
+    constructor(code: SearchErrorCode, message: string, extra?: SearchErrorExtra);
+}

package/lib/search/errors.js

@@ -0,0 +1,24 @@
+/**
+ * 检索错误：只区分调用方可处理的几类。
+ *
+ * - `bad_request`：参数不合法（关键词为空、年份区间倒置等）。
+ * - `not_found` / `conflict`：任务不存在、或与运行中/版本号冲突。
+ * - `upstream_error`：上游返回非 2xx 或响应不可解析。
+ * - `timeout` / `network_error`：请求超时或网络不可达。
+ *
+ * `status` / `retryAfterMs` 只用于限流判断，不进入对外错误信封。
+ */
+export class SearchError extends Error {
+    code;
+    status;
+    retryAfterMs;
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.name = 'SearchError';
+        this.code = code;
+        if (extra.status !== undefined)
+            this.status = extra.status;
+        if (extra.retryAfterMs !== undefined)
+            this.retryAfterMs = extra.retryAfterMs;
+    }
+}

package/lib/search/health.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 数据源运行时健康：限流冷却、最近一次成功/失败与延迟。
+ *
+ * 只存在于 Host 进程内，不落盘；重启后视为全新状态。`/health` 与设置页
+ * 诊断读取这里的快照，密钥不经过本模块。
+ */
+import type { SourceHealth, SourceId } from './types.js';
+export declare function cooldownUntil(id: SourceId): number;
+export declare function recordSourceOk(id: SourceId, latencyMs: number): void;
+export declare function recordSourceError(id: SourceId, message: string): void;
+export declare function recordSourceCooldown(id: SourceId, until: number, message: string): void;
+export declare function sourceHealthList(): SourceHealth[];
+export declare function resetSourceHealth(): void;

package/lib/search/health.js

@@ -0,0 +1,53 @@
+/**
+ * 数据源运行时健康：限流冷却、最近一次成功/失败与延迟。
+ *
+ * 只存在于 Host 进程内，不落盘；重启后视为全新状态。`/health` 与设置页
+ * 诊断读取这里的快照，密钥不经过本模块。
+ */
+import { SOURCE_IDS } from './types.js';
+const runtimes = new Map();
+function runtime(id) {
+    let current = runtimes.get(id);
+    if (current === undefined) {
+        current = {};
+        runtimes.set(id, current);
+    }
+    return current;
+}
+export function cooldownUntil(id) {
+    return runtime(id).cooldownUntil ?? 0;
+}
+export function recordSourceOk(id, latencyMs) {
+    const current = runtime(id);
+    current.lastOkAt = Date.now();
+    current.lastLatencyMs = Math.max(0, Math.round(latencyMs));
+    current.lastError = undefined;
+}
+export function recordSourceError(id, message) {
+    runtime(id).lastError = message;
+}
+export function recordSourceCooldown(id, until, message) {
+    const current = runtime(id);
+    current.cooldownUntil = Math.max(until, Date.now());
+    current.lastError = message;
+}
+export function sourceHealthList() {
+    const now = Date.now();
+    return SOURCE_IDS.map((id) => {
+        const current = runtime(id);
+        const health = { id };
+        if (current.lastOkAt !== undefined)
+            health.lastOkAt = new Date(current.lastOkAt).toISOString();
+        if (current.lastError !== undefined)
+            health.lastError = current.lastError;
+        if (current.lastLatencyMs !== undefined)
+            health.lastLatencyMs = current.lastLatencyMs;
+        if (current.cooldownUntil !== undefined && current.cooldownUntil > now) {
+            health.cooldownUntil = new Date(current.cooldownUntil).toISOString();
+        }
+        return health;
+    });
+}
+export function resetSourceHealth() {
+    runtimes.clear();
+}

package/lib/search/http.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 带超时与取消的上游请求。
+ *
+ * 所有 provider 共用这一条路径，保证错误码一致：超时 → `timeout`，
+ * 非 2xx → `upstream_error`（429 额外带 `retryAfterMs`），网络异常 → `network_error`。
+ */
+export interface HttpRequest {
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+    headers?: Record<string, string>;
+}
+export declare function fetchJson(url: string, request: HttpRequest): Promise<unknown>;
+export declare function fetchText(url: string, request: HttpRequest): Promise<string>;

package/lib/search/http.js

@@ -0,0 +1,81 @@
+/**
+ * 带超时与取消的上游请求。
+ *
+ * 所有 provider 共用这一条路径，保证错误码一致：超时 → `timeout`，
+ * 非 2xx → `upstream_error`（429 额外带 `retryAfterMs`），网络异常 → `network_error`。
+ */
+import { SearchError } from './errors.js';
+export async function fetchJson(url, request) {
+    const text = await fetchText(url, {
+        ...request,
+        headers: { accept: 'application/json', ...request.headers },
+    });
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new SearchError('upstream_error', `${safeHost(url)} 返回了无法解析的 JSON`);
+    }
+}
+export async function fetchText(url, request) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const onAbort = () => controller.abort();
+    if (request.signal?.aborted === true)
+        controller.abort();
+    else
+        request.signal?.addEventListener('abort', onAbort, { once: true });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, request.timeoutMs);
+    const host = safeHost(url);
+    try {
+        const response = await fetch(url, { headers: request.headers, signal: controller.signal });
+        if (!response.ok) {
+            const retryAfterMs = parseRetryAfter(response.headers.get('retry-after'));
+            const detail = response.status === 429
+                ? `${host} 触发限流（HTTP 429）`
+                : `${host} 返回 HTTP ${response.status}`;
+            throw new SearchError('upstream_error', detail, {
+                status: response.status,
+                ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+            });
+        }
+        return await response.text();
+    }
+    catch (error) {
+        if (error instanceof SearchError)
+            throw error;
+        if (timedOut) {
+            throw new SearchError('timeout', `${host} 请求超时（${request.timeoutMs} ms）`);
+        }
+        if (controller.signal.aborted) {
+            throw new SearchError('network_error', `${host} 请求已取消`);
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new SearchError('network_error', `无法访问 ${host}：${message}`);
+    }
+    finally {
+        clearTimeout(timer);
+        request.signal?.removeEventListener('abort', onAbort);
+    }
+}
+/** `Retry-After` 支持秒数与 HTTP 日期两种写法。 */
+function parseRetryAfter(value) {
+    if (value === null || value.trim() === '')
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const date = Date.parse(value);
+    return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+function safeHost(url) {
+    try {
+        return new URL(url).host;
+    }
+    catch {
+        return url;
+    }
+}

package/lib/search/identity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 跨源论文身份与合并。
+ *
+ * 身份优先级：DOI > PMID > PMCID > arXiv id > 标题键。标题键在 NFKC 归一化后
+ * 只保留字母数字，长度不足 12 个字符不参与合并（短标题误合并的代价太高）。
+ *
+ * 合并后按 RRF（reciprocal rank fusion）排序：Σ w_s / (60 + rank_s)，
+ * 命中源数、最佳排位、被引数与年份依次作为并列决胜。
+ */
+import type { Paper, PaperRecord, SourceId } from './types.js';
+export interface RankedHit {
+    record: PaperRecord;
+    source: SourceId;
+    /** 1-based 排位。 */
+    rank: number;
+    queryId: string;
+}
+export declare function normalizeTitle(title: string): string;
+/** 单条记录的身份键；无法可靠识别时回落到「源 + 内部 id」，保证不误合并。 */
+export declare function identityKey(record: PaperRecord): string;
+/** 由身份键生成稳定、URL 安全的 paperId（双 FNV-1a，16 位十六进制）。 */
+export declare function makePaperId(key: string): string;
+/** 把一次检索的命中合并成去重后的论文列表，并按 RRF 排序。 */
+export declare function mergeHits(hits: readonly RankedHit[]): Paper[];
+/** RRF 分数；供排序与调试使用。 */
+export declare function rrfScore(paper: Paper): number;
+export declare function comparePapers(a: Paper, b: Paper): number;

package/lib/search/identity.js

@@ -0,0 +1,154 @@
+/**
+ * 跨源论文身份与合并。
+ *
+ * 身份优先级：DOI > PMID > PMCID > arXiv id > 标题键。标题键在 NFKC 归一化后
+ * 只保留字母数字，长度不足 12 个字符不参与合并（短标题误合并的代价太高）。
+ *
+ * 合并后按 RRF（reciprocal rank fusion）排序：Σ w_s / (60 + rank_s)，
+ * 命中源数、最佳排位、被引数与年份依次作为并列决胜。
+ */
+import { SOURCE_IDS } from './types.js';
+/** 各源权重（与方案一致）。 */
+const RRF_WEIGHTS = {
+    pubmed: 1.1,
+    europepmc: 1.0,
+    openalex: 1.0,
+    crossref: 0.95,
+    semanticscholar: 0.9,
+    arxiv: 0.85,
+    pubtator: 0.7,
+};
+/** RRF 平滑常数。 */
+const RRF_K = 60;
+/** 标题键参与合并的最小长度（归一化后的字符数）。 */
+const MIN_TITLE_KEY = 12;
+export function normalizeTitle(title) {
+    return title
+        .normalize('NFKC')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, ' ')
+        .trim();
+}
+/** 单条记录的身份键；无法可靠识别时回落到「源 + 内部 id」，保证不误合并。 */
+export function identityKey(record) {
+    if (record.ids.doi !== '')
+        return `doi:${record.ids.doi}`;
+    if (record.ids.pmid !== '')
+        return `pmid:${record.ids.pmid}`;
+    if (record.ids.pmcid !== '')
+        return `pmcid:${record.ids.pmcid}`;
+    if (record.ids.arxivId !== '')
+        return `arxiv:${record.ids.arxivId}`;
+    const title = normalizeTitle(record.title);
+    if (title.length >= MIN_TITLE_KEY)
+        return `title:${title}:${record.year ?? ''}`;
+    return `src:${record.source}:${record.sourceId}`;
+}
+/** 由身份键生成稳定、URL 安全的 paperId（双 FNV-1a，16 位十六进制）。 */
+export function makePaperId(key) {
+    const a = fnv1a(key, 0x811c9dc5);
+    const b = fnv1a(key, 0x01000193);
+    return a.toString(16).padStart(8, '0') + b.toString(16).padStart(8, '0');
+}
+function fnv1a(text, seed) {
+    let hash = seed >>> 0;
+    for (let index = 0; index < text.length; index += 1) {
+        hash ^= text.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}
+/** 把一次检索的命中合并成去重后的论文列表，并按 RRF 排序。 */
+export function mergeHits(hits) {
+    const groups = new Map();
+    for (const hit of hits) {
+        const key = identityKey(hit.record);
+        const group = groups.get(key);
+        if (group === undefined) {
+            groups.set(key, { base: { ...hit.record }, hits: [hit] });
+        }
+        else {
+            mergeRecord(group.base, hit.record);
+            group.hits.push(hit);
+        }
+    }
+    const papers = [...groups.entries()].map(([key, group]) => {
+        const hitSources = [];
+        const matchedQueries = new Set();
+        for (const hit of group.hits) {
+            matchedQueries.add(hit.queryId);
+            const existing = hitSources.find((entry) => entry.source === hit.source);
+            if (existing === undefined)
+                hitSources.push({ source: hit.source, rank: hit.rank });
+            else
+                existing.rank = Math.min(existing.rank, hit.rank);
+        }
+        hitSources.sort((a, b) => SOURCE_IDS.indexOf(a.source) - SOURCE_IDS.indexOf(b.source));
+        return {
+            ...group.base,
+            paperId: makePaperId(key),
+            hitSources,
+            matchedQueries: [...matchedQueries],
+        };
+    });
+    return papers.sort(comparePapers);
+}
+/** RRF 分数；供排序与调试使用。 */
+export function rrfScore(paper) {
+    let score = 0;
+    for (const hit of paper.hitSources) {
+        score += (RRF_WEIGHTS[hit.source] ?? 1) / (RRF_K + hit.rank);
+    }
+    return score;
+}
+export function comparePapers(a, b) {
+    const score = rrfScore(b) - rrfScore(a);
+    if (score !== 0)
+        return score;
+    const sources = b.hitSources.length - a.hitSources.length;
+    if (sources !== 0)
+        return sources;
+    const best = bestRank(a) - bestRank(b);
+    if (best !== 0)
+        return best;
+    const citations = (b.citedBy ?? -1) - (a.citedBy ?? -1);
+    if (citations !== 0)
+        return citations;
+    return (b.year ?? 0) - (a.year ?? 0);
+}
+function bestRank(paper) {
+    return paper.hitSources.reduce((min, hit) => Math.min(min, hit.rank), Number.POSITIVE_INFINITY);
+}
+function mergeRecord(base, extra) {
+    base.ids = mergeIds(base.ids, extra.ids);
+    if (base.ids.doi !== '')
+        base.doi = base.ids.doi;
+    if (extra.abstract.length > base.abstract.length)
+        base.abstract = extra.abstract;
+    if (base.pdfUrl === '' && extra.pdfUrl !== '')
+        base.pdfUrl = extra.pdfUrl;
+    if (extra.venue.length > base.venue.length)
+        base.venue = extra.venue;
+    if (base.year === null)
+        base.year = extra.year;
+    if (base.citedBy === null || (extra.citedBy !== null && extra.citedBy > base.citedBy)) {
+        base.citedBy = extra.citedBy;
+    }
+    if (extra.authors.length > base.authors.length)
+        base.authors = [...extra.authors];
+    if (base.language === undefined && extra.language !== undefined)
+        base.language = extra.language;
+    if (base.type === '' && extra.type !== '')
+        base.type = extra.type;
+    if (base.url === '' || base.url === base.sourceId)
+        base.url = extra.url;
+    base.openAccess = base.openAccess || extra.openAccess;
+}
+function mergeIds(base, extra) {
+    return {
+        doi: base.doi !== '' ? base.doi : extra.doi,
+        pmid: base.pmid !== '' ? base.pmid : extra.pmid,
+        pmcid: base.pmcid !== '' ? base.pmcid : extra.pmcid,
+        arxivId: base.arxivId !== '' ? base.arxivId : extra.arxivId,
+    };
+}

package/lib/search/normalize.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 上游 JSON 的窄化与归一化助手。
+ *
+ * 免费 API 的字段普遍可空、类型漂移，因此统一在 provider 边界做一次
+ * 「未知 → 安全值」的转换，聚合层之后只处理规整的 `Paper`。
+ */
+export declare function asRecord(value: unknown): Record<string, unknown>;
+export declare function asArray(value: unknown): unknown[];
+export declare function asString(value: unknown): string;
+export declare function asNumber(value: unknown): number | null;
+/** 去掉 `https://doi.org/` / `doi:` 前缀并转小写。 */
+export declare function normalizeDoi(value: unknown): string;
+export declare function doiUrl(doi: string): string;
+/** 取字符串数组的第一项（Crossref 的 title / container-title）。 */
+export declare function firstString(value: unknown): string;
+/** 去掉 JATS/HTML 标签与常见实体，压成单行文本。 */
+export declare function stripTags(value: unknown): string;

package/lib/search/normalize.js

@@ -0,0 +1,47 @@
+/**
+ * 上游 JSON 的窄化与归一化助手。
+ *
+ * 免费 API 的字段普遍可空、类型漂移，因此统一在 provider 边界做一次
+ * 「未知 → 安全值」的转换，聚合层之后只处理规整的 `Paper`。
+ */
+export function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+export function asString(value) {
+    return typeof value === 'string' ? value : '';
+}
+export function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/** 去掉 `https://doi.org/` / `doi:` 前缀并转小写。 */
+export function normalizeDoi(value) {
+    return asString(value)
+        .trim()
+        .replace(/^https?:\/\/(?:dx\.)?doi\.org\//iu, '')
+        .replace(/^doi:\s*/iu, '')
+        .toLowerCase();
+}
+export function doiUrl(doi) {
+    return doi === '' ? '' : `https://doi.org/${doi}`;
+}
+/** 取字符串数组的第一项（Crossref 的 title / container-title）。 */
+export function firstString(value) {
+    return asString(asArray(value)[0]);
+}
+/** 去掉 JATS/HTML 标签与常见实体，压成单行文本。 */
+export function stripTags(value) {
+    return asString(value)
+        .replace(/<[^>]*>/gu, ' ')
+        .replace(/&lt;/gu, '<')
+        .replace(/&gt;/gu, '>')
+        .replace(/&quot;/gu, '"')
+        .replace(/&#39;/gu, "'")
+        .replace(/&amp;/gu, '&')
+        .replace(/\s+/gu, ' ')
+        .trim();
+}

package/lib/search/oa.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 开放获取全文定位：候选 PDF 与 Europe PMC HTML 全文。
+ *
+ * 候选只负责“可能在哪”，真正的下载与安全校验在 Host 侧（`host/pdf/store.ts`）。
+ */
+import type { Paper } from './types.js';
+/** 去重后的 PDF 候选地址（顺序即尝试优先级）。 */
+export declare function pdfCandidates(paper: Paper): string[];
+/** Europe PMC 的全文 XML 地址；没有 PMCID 时返回 null。 */
+export declare function epmcXmlUrl(paper: Paper): string | null;
+/** Unpaywall 查询（需要联系邮箱，遵守其 polite pool）。 */
+export declare function unpaywallPdfCandidates(doi: string, email: string, timeoutMs: number, signal?: AbortSignal): Promise<string[]>;
+/**
+ * JATS XML → 可读 HTML 片段。
+ *
+ * 只保留标题、段落、列表等结构，其余标签一律剥离；所有文本先转义，
+ * 因此上游 XML 里的脚本/属性不会进入阅读页。
+ */
+export declare function jatsToHtml(xml: string): string;
+/** 包一层最小阅读页样式。 */
+export declare function fullTextHtml(paper: Paper, fragment: string, source: string): string;