dsh-plugin-litsearch 0.0.0-stage → 0.2.0

package/lib/search/oa.js

@@ -0,0 +1,149 @@
+/**
+ * 开放获取全文定位：候选 PDF 与 Europe PMC HTML 全文。
+ *
+ * 候选只负责“可能在哪”，真正的下载与安全校验在 Host 侧（`host/pdf/store.ts`）。
+ */
+const EPMC_REST = 'https://www.ebi.ac.uk/europepmc/webservices/rest';
+const EPMC_ARTICLE = 'https://europepmc.org/articles';
+const PMC_ARTICLE = 'https://www.ncbi.nlm.nih.gov/pmc/articles';
+const ARXIV_PDF = 'https://arxiv.org/pdf';
+const UNPAYWALL_API = 'https://api.unpaywall.org/v2';
+/** 去重后的 PDF 候选地址（顺序即尝试优先级）。 */
+export function pdfCandidates(paper) {
+    const candidates = new Set();
+    if (paper.pdfUrl !== '')
+        candidates.add(paper.pdfUrl);
+    const pmcid = normalizePmcid(paper.ids.pmcid);
+    if (pmcid !== '') {
+        candidates.add(`${EPMC_ARTICLE}/${pmcid}?pdf=render`);
+        candidates.add(`${PMC_ARTICLE}/${pmcid}/pdf/`);
+    }
+    if (paper.ids.arxivId !== '')
+        candidates.add(`${ARXIV_PDF}/${paper.ids.arxivId}`);
+    return [...candidates];
+}
+/** Europe PMC 的全文 XML 地址；没有 PMCID 时返回 null。 */
+export function epmcXmlUrl(paper) {
+    const pmcid = normalizePmcid(paper.ids.pmcid);
+    return pmcid === '' ? null : `${EPMC_REST}/${pmcid}/fullTextXML`;
+}
+/** Unpaywall 查询（需要联系邮箱，遵守其 polite pool）。 */
+export async function unpaywallPdfCandidates(doi, email, timeoutMs, signal) {
+    if (doi === '' || email === '')
+        return [];
+    const url = `${UNPAYWALL_API}/${encodeURIComponent(doi)}?email=${encodeURIComponent(email)}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const onAbort = () => controller.abort();
+    signal?.addEventListener('abort', onAbort);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        if (!response.ok)
+            return [];
+        const body = (await response.json());
+        const urls = new Set();
+        const best = asRecord(body['best_oa_location']);
+        const bestPdf = asString(best['url_for_pdf']);
+        if (bestPdf !== '')
+            urls.add(bestPdf);
+        for (const raw of asArray(body['oa_locations'])) {
+            const pdf = asString(asRecord(raw)['url_for_pdf']);
+            if (pdf !== '')
+                urls.add(pdf);
+        }
+        return [...urls];
+    }
+    catch {
+        return [];
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+    }
+}
+function normalizePmcid(value) {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return '';
+    return /^\d+$/u.test(trimmed) ? `PMC${trimmed}` : trimmed;
+}
+/**
+ * JATS XML → 可读 HTML 片段。
+ *
+ * 只保留标题、段落、列表等结构，其余标签一律剥离；所有文本先转义，
+ * 因此上游 XML 里的脚本/属性不会进入阅读页。
+ */
+export function jatsToHtml(xml) {
+    let body = xml;
+    const start = body.indexOf('<body');
+    const end = body.lastIndexOf('</body>');
+    if (start >= 0 && end > start)
+        body = body.slice(start, end + '</body>'.length);
+    body = body.replace(/<back[\s\S]*?<\/back>/gu, '');
+    body = body.replace(/<ref-list[\s\S]*?<\/ref-list>/gu, '');
+    const P_OPEN = '\u0001popen\u0001';
+    const P_CLOSE = '\u0001pclose\u0001';
+    const T_OPEN = '\u0001h3open\u0001';
+    const T_CLOSE = '\u0001h3close\u0001';
+    const LI_OPEN = '\u0001li_open\u0001';
+    const LI_CLOSE = '\u0001li_close\u0001';
+    const UL_OPEN = '\u0001ul_open\u0001';
+    const UL_CLOSE = '\u0001ul_close\u0001';
+    let marked = body.replace(/<(\/?)p\b[^>]*>/gu, (_match, close) => close === '/' ? P_CLOSE : P_OPEN);
+    marked = marked.replace(/<(\/?)title\b[^>]*>/gu, (_match, close) => close === '/' ? T_CLOSE : T_OPEN);
+    marked = marked.replace(/<(\/?)list-item\b[^>]*>/gu, (_match, close) => close === '/' ? LI_CLOSE : LI_OPEN);
+    marked = marked.replace(/<(\/?)list\b[^>]*>/gu, (_match, close) => close === '/' ? UL_CLOSE : UL_OPEN);
+    const text = marked.replace(/<[^>]+>/gu, ' ').replace(/[ \t]+/gu, ' ');
+    const escaped = escapeHtml(text);
+    return escaped
+        .replace(/\u0001popen\u0001/gu, '<p>')
+        .replace(/\u0001pclose\u0001/gu, '</p>')
+        .replace(/\u0001h3open\u0001/gu, '<h3>')
+        .replace(/\u0001h3close\u0001/gu, '</h3>')
+        .replace(/\u0001li_open\u0001/gu, '<li>')
+        .replace(/\u0001li_close\u0001/gu, '</li>')
+        .replace(/\u0001ul_open\u0001/gu, '<ul>')
+        .replace(/\u0001ul_close\u0001/gu, '</ul>');
+}
+/** 包一层最小阅读页样式。 */
+export function fullTextHtml(paper, fragment, source) {
+    return `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(paper.title)}</title>
+<style>
+  body { margin: 0; padding: 16px; font: 14px/1.7 -apple-system, "PingFang SC", sans-serif; color: #222; }
+  h1 { font-size: 18px; line-height: 1.4; margin: 0 0 4px; }
+  h3 { font-size: 15px; margin: 18px 0 6px; }
+  p { margin: 0 0 10px; }
+  .meta { font-size: 12px; color: #666; margin-bottom: 16px; }
+  a { color: #2563eb; }
+</style>
+</head>
+<body>
+<h1>${escapeHtml(paper.title)}</h1>
+<div class="meta">${escapeHtml(source)} · <a href="${escapeHtml(paper.url)}" target="_blank" rel="noreferrer">原文</a></div>
+${fragment}
+</body>
+</html>`;
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/gu, '&amp;')
+        .replace(/</gu, '&lt;')
+        .replace(/>/gu, '&gt;')
+        .replace(/"/gu, '&quot;');
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function asString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}

package/lib/search/providers/arxiv.d.ts

@@ -0,0 +1,9 @@
+/**
+ * arXiv provider —— 预印本检索。
+ *
+ * 文档：https://info.arxiv.org/help/api/user-manual.html
+ * 检索式需带 `all:` 等字段前缀（由 query-adapter 处理）；API 要求 3s 间隔。
+ * 年份与 OA 只能后置过滤（arXiv 全部开放获取）。
+ */
+import type { Provider } from '../types.js';
+export declare const arxiv: Provider;

package/lib/search/providers/arxiv.js

@@ -0,0 +1,99 @@
+/**
+ * arXiv provider —— 预印本检索。
+ *
+ * 文档：https://info.arxiv.org/help/api/user-manual.html
+ * 检索式需带 `all:` 等字段前缀（由 query-adapter 处理）；API 要求 3s 间隔。
+ * 年份与 OA 只能后置过滤（arXiv 全部开放获取）。
+ */
+import { asNumber, asString, normalizeDoi } from '../normalize.js';
+import { limitedText } from '../rate-limit.js';
+import { xmlAttr, xmlBlocks, xmlTag, xmlText, xmlTexts } from '../xml.js';
+const ENDPOINT = 'https://export.arxiv.org/api/query';
+export const arxiv = {
+    info: {
+        id: 'arxiv',
+        label: 'arXiv',
+        homepage: 'https://arxiv.org',
+        capabilities: { abstract: true, citationCount: false, openAccess: true, pdf: true },
+        rateLimit: '3s 间隔（自限）',
+        syntax: '需要 all:/ti:/abs: 等前缀；通用关键词会自动转换，年份为后置筛选',
+        optionalKey: false,
+    },
+    async search(query, options) {
+        const params = new URLSearchParams({
+            search_query: query,
+            start: '0',
+            max_results: String(options.limit),
+            sortBy: 'relevance',
+            sortOrder: 'descending',
+        });
+        const xml = await limitedText('arxiv', `${ENDPOINT}?${params.toString()}`, {
+            timeoutMs: options.timeoutMs,
+            signal: options.signal,
+            bypassCooldown: options.bypassCooldown === true,
+            headers: { accept: 'application/atom+xml' },
+        });
+        const papers = xmlBlocks(xml, 'entry')
+            .map(mapEntry)
+            .filter((paper) => paper.title !== '');
+        return filterByYear(papers, options);
+    },
+};
+function mapEntry(entry) {
+    const arxivId = normalizeArxiv(xmlText(entry, 'id'));
+    const doi = normalizeDoi(xmlText(entry, 'arxiv:doi'));
+    const published = xmlText(entry, 'published');
+    const pdfUrl = findPdfUrl(entry);
+    const categoryTag = xmlTag(entry, 'category');
+    const category = xmlAttr(categoryTag, 'term');
+    return {
+        source: 'arxiv',
+        sourceId: arxivId,
+        ids: { doi, pmid: '', pmcid: '', arxivId },
+        title: xmlText(entry, 'title'),
+        authors: xmlTexts(entry, 'name').filter((name) => name !== ''),
+        year: readYear(published),
+        venue: xmlText(entry, 'arxiv:journal_ref') || 'arXiv',
+        doi,
+        url: arxivId === '' ? '' : `https://arxiv.org/abs/${arxivId}`,
+        abstract: xmlText(entry, 'summary'),
+        citedBy: null,
+        openAccess: true,
+        pdfUrl,
+        type: category === '' ? 'preprint' : `preprint/${category}`,
+    };
+}
+function findPdfUrl(entry) {
+    for (const match of entry.matchAll(/<link\b[^>]*>/gu)) {
+        const tag = match[0];
+        const title = xmlAttr(tag, 'title').toLowerCase();
+        const type = xmlAttr(tag, 'type').toLowerCase();
+        if (title === 'pdf' || type === 'application/pdf') {
+            return xmlAttr(tag, 'href').replace(/^http:/u, 'https:');
+        }
+    }
+    return '';
+}
+function normalizeArxiv(value) {
+    const trimmed = asString(value).trim().replace(/\/+$/u, '');
+    if (trimmed === '')
+        return '';
+    const segment = trimmed.split('/').pop() ?? '';
+    return segment.replace(/v\d+$/u, '');
+}
+function readYear(value) {
+    const match = /(\d{4})/u.exec(value);
+    return match === null ? null : asNumber(Number(match[1]));
+}
+function filterByYear(papers, options) {
+    if (options.yearFrom === undefined && options.yearTo === undefined)
+        return papers;
+    return papers.filter((paper) => {
+        if (options.yearFrom !== undefined && (paper.year ?? 0) < options.yearFrom)
+            return false;
+        if (options.yearTo !== undefined && (paper.year ?? Number.MAX_SAFE_INTEGER) > options.yearTo) {
+            return false;
+        }
+        return true;
+    });
+}

package/lib/search/providers/crossref.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Crossref provider —— DOI 注册元数据，几乎覆盖全部正式出版物。
+ *
+ * 文档：https://www.crossref.org/documentation/retrieve-metadata/rest-api/
+ * 无需密钥；带 `mailto` 可进入 polite pool。
+ */
+import type { Provider } from '../types.js';
+export declare const crossref: Provider;

package/lib/search/providers/crossref.js

@@ -0,0 +1,107 @@
+/**
+ * Crossref provider —— DOI 注册元数据，几乎覆盖全部正式出版物。
+ *
+ * 文档：https://www.crossref.org/documentation/retrieve-metadata/rest-api/
+ * 无需密钥；带 `mailto` 可进入 polite pool。
+ */
+import { limitedJson } from '../rate-limit.js';
+import { asArray, asNumber, asRecord, asString, doiUrl, firstString, normalizeDoi, stripTags, } from '../normalize.js';
+const ENDPOINT = 'https://api.crossref.org/works';
+const SELECT_FIELDS = [
+    'DOI',
+    'title',
+    'author',
+    'issued',
+    'container-title',
+    'publisher',
+    'URL',
+    'abstract',
+    'is-referenced-by-count',
+    'link',
+    'license',
+    'type',
+].join(',');
+function userAgent(contactEmail) {
+    return contactEmail === ''
+        ? 'dsh-plugin-litsearch/0.1.0'
+        : `dsh-plugin-litsearch/0.1.0 (mailto:${contactEmail})`;
+}
+export const crossref = {
+    info: {
+        id: 'crossref',
+        label: 'Crossref',
+        homepage: 'https://www.crossref.org',
+        capabilities: { abstract: true, citationCount: true, openAccess: false, pdf: true },
+        rateLimit: '约 1 req/s（保守自限）；带邮箱进入 polite pool',
+        syntax: '自然语言；按年份下推，OA 由许可证粗略判断',
+        optionalKey: false,
+    },
+    async search(query, options) {
+        const params = new URLSearchParams({
+            query,
+            rows: String(options.limit),
+            select: SELECT_FIELDS,
+        });
+        const filters = [];
+        if (options.yearFrom !== undefined)
+            filters.push(`from-pub-date:${options.yearFrom}-01-01`);
+        if (options.yearTo !== undefined)
+            filters.push(`until-pub-date:${options.yearTo}-12-31`);
+        if (filters.length > 0)
+            params.set('filter', filters.join(','));
+        if (options.contactEmail !== '')
+            params.set('mailto', options.contactEmail);
+        const payload = await limitedJson('crossref', `${ENDPOINT}?${params.toString()}`, {
+            timeoutMs: options.timeoutMs,
+            signal: options.signal,
+            bypassCooldown: options.bypassCooldown === true,
+            headers: {
+                accept: 'application/json',
+                'user-agent': userAgent(options.contactEmail),
+            },
+        });
+        const items = asArray(asRecord(asRecord(payload)['message'])['items']);
+        const papers = items.map(mapItem).filter((paper) => paper.title !== '');
+        return options.openAccessOnly ? papers.filter((paper) => paper.openAccess) : papers;
+    },
+};
+function mapItem(raw) {
+    const item = asRecord(raw);
+    const doi = normalizeDoi(item['DOI']);
+    const links = asArray(item['link']).map(asRecord);
+    const pdfLink = links.find((link) => asString(link['content-type']) === 'application/pdf');
+    const licenseText = asArray(item['license'])
+        .map((entry) => asString(asRecord(entry)['URL']))
+        .join(' ');
+    const issued = asArray(asRecord(item['issued'])['date-parts'])[0];
+    const language = asString(item['language']);
+    return {
+        source: 'crossref',
+        sourceId: doi,
+        ids: { doi, pmid: '', pmcid: '', arxivId: '' },
+        title: stripTags(firstString(item['title'])),
+        authors: asArray(item['author'])
+            .map(authorName)
+            .filter((name) => name !== ''),
+        year: asNumber(asArray(issued)[0]),
+        venue: stripTags(firstString(item['container-title'])) || asString(item['publisher']),
+        doi,
+        url: asString(item['URL']) || doiUrl(doi),
+        abstract: stripTags(item['abstract']),
+        ...(language === '' ? {} : { language }),
+        citedBy: asNumber(item['is-referenced-by-count']),
+        // Crossref 没有统一的 OA 标志，这里按许可证 URL 粗略判断。
+        openAccess: /creativecommons|open\s*access/iu.test(licenseText),
+        pdfUrl: pdfLink === undefined ? '' : asString(pdfLink['URL']),
+        type: asString(item['type']),
+    };
+}
+function authorName(raw) {
+    const author = asRecord(raw);
+    const name = asString(author['name']);
+    if (name !== '')
+        return name;
+    return [asString(author['given']), asString(author['family'])]
+        .filter((part) => part !== '')
+        .join(' ');
+}

package/lib/search/providers/europepmc.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Europe PMC provider —— 生命科学文献聚合，覆盖 PubMed、PMC、预印本。
+ *
+ * 文档：https://europepmc.org/RestfulWebService
+ * 无需密钥；自限约 5 req/s（队列里按 200ms 间隔）。
+ */
+import type { Provider } from '../types.js';
+export declare const europepmc: Provider;

package/lib/search/providers/europepmc.js

@@ -0,0 +1,105 @@
+/**
+ * Europe PMC provider —— 生命科学文献聚合，覆盖 PubMed、PMC、预印本。
+ *
+ * 文档：https://europepmc.org/RestfulWebService
+ * 无需密钥；自限约 5 req/s（队列里按 200ms 间隔）。
+ */
+import { asArray, asNumber, asRecord, asString, normalizeDoi } from '../normalize.js';
+import { limitedJson } from '../rate-limit.js';
+const ENDPOINT = 'https://www.ebi.ac.uk/europepmc/webservices/rest/search';
+/**
+ * `resultType=core` 加上较大的 pageSize 时响应明显偏慢，15s 会把正常请求
+ * 误判成超时（全文接口本来就用 30s）。检索请求固定给 25s 下限，设置里
+ * 调高全局超时仍然生效。
+ */
+const SEARCH_TIMEOUT_FLOOR_MS = 25_000;
+export const europepmc = {
+    info: {
+        id: 'europepmc',
+        label: 'Europe PMC',
+        homepage: 'https://europepmc.org',
+        capabilities: { abstract: true, citationCount: true, openAccess: true, pdf: true },
+        rateLimit: '约 5 req/s（自限）',
+        syntax: '支持布尔语法，查询式与 PubMed 接近；可按 PUB_YEAR / OPEN_ACCESS 下推',
+        optionalKey: false,
+    },
+    async search(query, options) {
+        const params = new URLSearchParams({
+            query: buildQuery(query, options),
+            format: 'json',
+            pageSize: String(options.limit),
+            resultType: 'core',
+        });
+        const payload = await limitedJson('europepmc', `${ENDPOINT}?${params.toString()}`, {
+            timeoutMs: Math.max(options.timeoutMs, SEARCH_TIMEOUT_FLOOR_MS),
+            signal: options.signal,
+            bypassCooldown: options.bypassCooldown === true,
+            headers: { accept: 'application/json' },
+        });
+        const results = asArray(asRecord(asRecord(payload)['resultList'])['result']);
+        return results.map(mapResult).filter((paper) => paper.title !== '');
+    },
+};
+function buildQuery(query, options) {
+    const clauses = [];
+    if (options.yearFrom !== undefined || options.yearTo !== undefined) {
+        clauses.push(`PUB_YEAR:[${options.yearFrom ?? 1800} TO ${options.yearTo ?? 3000}]`);
+    }
+    if (options.openAccessOnly)
+        clauses.push('OPEN_ACCESS:y');
+    if (clauses.length === 0)
+        return query;
+    return `(${query}) AND ${clauses.join(' AND ')}`;
+}
+function mapResult(raw) {
+    const result = asRecord(raw);
+    const id = asString(result['id']);
+    const source = asString(result['source']);
+    const pmid = asString(result['pmid']);
+    const pmcid = normalizePmcid(asString(result['pmcid']));
+    const doi = normalizeDoi(result['doi']);
+    const language = asString(result['language']);
+    const authors = asArray(asRecord(result['authorList'])['author'])
+        .map((entry) => asString(asRecord(entry)['fullName']))
+        .filter((name) => name !== '');
+    const pdfUrl = pickPdfUrl(result['fullTextUrlList']);
+    const journal = asRecord(asRecord(result['journalInfo'])['journal']);
+    return {
+        source: 'europepmc',
+        sourceId: id,
+        ids: { doi, pmid, pmcid, arxivId: '' },
+        title: asString(result['title']),
+        authors,
+        year: readYear(result['pubYear']),
+        venue: asString(journal['title']),
+        doi,
+        url: source === '' || id === '' ? '' : `https://europepmc.org/article/${source}/${id}`,
+        abstract: asString(result['abstractText']),
+        ...(language === '' ? {} : { language }),
+        citedBy: asNumber(result['citedByCount']),
+        openAccess: asString(result['isOpenAccess']).toUpperCase() === 'Y',
+        pdfUrl,
+        type: asArray(asRecord(result['pubTypeList'])['pubType']).map(asString)[0] ?? '',
+    };
+}
+function pickPdfUrl(value) {
+    const urls = asArray(asRecord(value)['fullTextUrl']).map(asRecord);
+    const pdf = urls.find((entry) => {
+        const style = asString(entry['documentStyle']).toLowerCase();
+        const url = asString(entry['url']).toLowerCase();
+        const availability = asString(entry['availabilityCode']).toUpperCase();
+        return (style === 'pdf' || url.endsWith('.pdf')) && (availability === 'OA' || availability === 'F');
+    });
+    return pdf === undefined ? '' : asString(pdf['url']);
+}
+function normalizePmcid(value) {
+    const trimmed = value.trim().toUpperCase();
+    if (trimmed === '')
+        return '';
+    return trimmed.startsWith('PMC') ? trimmed : `PMC${trimmed}`;
+}
+function readYear(value) {
+    const text = asString(value);
+    const match = /(\d{4})/u.exec(text);
+    return match === null ? null : asNumber(Number(match[1]));
+}

package/lib/search/providers/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 数据源注册表。
+ *
+ * 新增数据源：实现 `Provider` → 在 {@link PROVIDERS} 登记 → 把 id 加进
+ * `types.ts` 的 `SOURCE_IDS`，并补中英文案。
+ */
+import type { Provider, ProviderInfo, SourceId } from '../types.js';
+export declare const PROVIDERS: Record<SourceId, Provider>;
+/** 注册顺序即聚合展示顺序。 */
+export declare const PROVIDER_INFOS: readonly ProviderInfo[];
+export declare function isSourceId(value: string): value is SourceId;
+/** 把外部输入解析为合法 id 列表；空输入表示全部数据源。 */
+export declare function resolveSources(requested: readonly string[] | undefined): SourceId[];

package/lib/search/providers/index.js

@@ -0,0 +1,34 @@
+/**
+ * 数据源注册表。
+ *
+ * 新增数据源：实现 `Provider` → 在 {@link PROVIDERS} 登记 → 把 id 加进
+ * `types.ts` 的 `SOURCE_IDS`，并补中英文案。
+ */
+import { SOURCE_IDS } from '../types.js';
+import { arxiv } from './arxiv.js';
+import { crossref } from './crossref.js';
+import { europepmc } from './europepmc.js';
+import { openalex } from './openalex.js';
+import { pubmed } from './pubmed.js';
+import { pubtator } from './pubtator.js';
+import { semanticscholar } from './semanticscholar.js';
+export const PROVIDERS = {
+    pubmed,
+    europepmc,
+    openalex,
+    crossref,
+    semanticscholar,
+    arxiv,
+    pubtator,
+};
+/** 注册顺序即聚合展示顺序。 */
+export const PROVIDER_INFOS = SOURCE_IDS.map((id) => PROVIDERS[id].info);
+export function isSourceId(value) {
+    return SOURCE_IDS.includes(value);
+}
+/** 把外部输入解析为合法 id 列表；空输入表示全部数据源。 */
+export function resolveSources(requested) {
+    if (requested === undefined || requested.length === 0)
+        return [...SOURCE_IDS];
+    return SOURCE_IDS.filter((id) => requested.includes(id));
+}

package/lib/search/providers/openalex.d.ts

@@ -0,0 +1,8 @@
+/**
+ * OpenAlex provider —— 覆盖面最广的免费开放学术图谱。
+ *
+ * 文档：https://docs.openalex.org
+ * 无需密钥；带 `mailto` 进入 polite pool，可获得更稳定的限流额度。
+ */
+import type { Provider } from '../types.js';
+export declare const openalex: Provider;

package/lib/search/providers/openalex.js

@@ -0,0 +1,109 @@
+/**
+ * OpenAlex provider —— 覆盖面最广的免费开放学术图谱。
+ *
+ * 文档：https://docs.openalex.org
+ * 无需密钥；带 `mailto` 进入 polite pool，可获得更稳定的限流额度。
+ */
+import { limitedJson } from '../rate-limit.js';
+import { asArray, asNumber, asRecord, asString, doiUrl, normalizeDoi } from '../normalize.js';
+const ENDPOINT = 'https://api.openalex.org/works';
+function userAgent(contactEmail) {
+    return contactEmail === ''
+        ? 'dsh-plugin-litsearch/0.1.0'
+        : `dsh-plugin-litsearch/0.1.0 (mailto:${contactEmail})`;
+}
+export const openalex = {
+    info: {
+        id: 'openalex',
+        label: 'OpenAlex',
+        homepage: 'https://openalex.org',
+        capabilities: { abstract: true, citationCount: true, openAccess: true, pdf: true },
+        rateLimit: '约 10 req/s；带邮箱进入 polite pool',
+        syntax: '自然语言；支持按年份与 OA 下推，不支持字段标签',
+        optionalKey: false,
+    },
+    async search(query, options) {
+        const params = new URLSearchParams({
+            search: query,
+            'per-page': String(options.limit),
+            sort: 'relevance_score:desc',
+        });
+        const filters = [];
+        if (options.yearFrom !== undefined)
+            filters.push(`from_publication_date:${options.yearFrom}-01-01`);
+        if (options.yearTo !== undefined)
+            filters.push(`to_publication_date:${options.yearTo}-12-31`);
+        if (options.openAccessOnly)
+            filters.push('is_oa:true');
+        if (filters.length > 0)
+            params.set('filter', filters.join(','));
+        if (options.contactEmail !== '')
+            params.set('mailto', options.contactEmail);
+        const payload = await limitedJson('openalex', `${ENDPOINT}?${params.toString()}`, {
+            timeoutMs: options.timeoutMs,
+            signal: options.signal,
+            bypassCooldown: options.bypassCooldown === true,
+            headers: {
+                accept: 'application/json',
+                'user-agent': userAgent(options.contactEmail),
+            },
+        });
+        return asArray(asRecord(payload)['results'])
+            .map(mapWork)
+            .filter((paper) => paper.title !== '');
+    },
+};
+function mapWork(raw) {
+    const work = asRecord(raw);
+    const primary = asRecord(work['primary_location']);
+    const host = asRecord(primary['source']);
+    const bestOa = asRecord(work['best_oa_location']);
+    const ids = asRecord(work['ids']);
+    const doi = normalizeDoi(work['doi']);
+    const openAlexId = asString(work['id']);
+    const landing = asString(primary['landing_page_url']);
+    const language = asString(work['language']);
+    return {
+        source: 'openalex',
+        sourceId: openAlexId,
+        ids: {
+            doi,
+            pmid: normalizeId(ids['pmid']),
+            pmcid: normalizeId(ids['pmcid']),
+            arxivId: '',
+        },
+        title: asString(work['title']) || asString(work['display_name']),
+        authors: asArray(work['authorships'])
+            .map((entry) => asString(asRecord(asRecord(entry)['author'])['display_name']))
+            .filter((name) => name !== ''),
+        year: asNumber(work['publication_year']),
+        venue: asString(host['display_name']),
+        doi,
+        url: landing || doiUrl(doi) || openAlexId,
+        abstract: abstractFromInverted(work['abstract_inverted_index']),
+        ...(language === '' ? {} : { language }),
+        citedBy: asNumber(work['cited_by_count']),
+        openAccess: asRecord(work['open_access'])['is_oa'] === true,
+        pdfUrl: asString(bestOa['pdf_url']),
+        type: asString(work['type']),
+    };
+}
+/** OpenAlex 的 ids 是完整 URL，取末段作为裸 id。 */
+function normalizeId(value) {
+    return asString(value).replace(/\/+$/u, '').split('/').pop() ?? '';
+}
+/** OpenAlex 的摘要是「词 → 位置数组」，按位置还原成原文。 */
+function abstractFromInverted(value) {
+    const index = asRecord(value);
+    const entries = [];
+    for (const [word, positions] of Object.entries(index)) {
+        for (const position of asArray(positions)) {
+            if (typeof position === 'number')
+                entries.push([position, word]);
+        }
+    }
+    return entries
+        .sort((a, b) => a[0] - b[0])
+        .map(([, word]) => word)
+        .join(' ');
+}

package/lib/search/providers/pubmed.d.ts

@@ -0,0 +1,10 @@
+/**
+ * PubMed / NCBI E-utilities provider。
+ *
+ * 两次请求：ESearch 拿 PMID 列表 → EFetch 取 XML 详情。ESearch/EFetch 各自
+ * 走 PubMed 限流队列（默认 350ms，带 key 可在设置里调低）。
+ *
+ * 文档：docs/eutilities（使用规范、ESearch、EFetch）
+ */
+import type { Provider } from '../types.js';
+export declare const pubmed: Provider;