dsh-plugin-litsearch 0.2.0 → 0.3.5

package/lib/search/oa.js

@@ -13,6 +13,9 @@ export function pdfCandidates(paper) {
     const candidates = new Set();
     if (paper.pdfUrl !== '')
         candidates.add(paper.pdfUrl);
+    const publisher = publisherPdfUrl(paper.doi);
+    if (publisher !== null)
+        candidates.add(publisher);
     const pmcid = normalizePmcid(paper.ids.pmcid);
     if (pmcid !== '') {
         candidates.add(`${EPMC_ARTICLE}/${pmcid}?pdf=render`);
@@ -22,6 +25,44 @@ export function pdfCandidates(paper) {
         candidates.add(`${ARXIV_PDF}/${paper.ids.arxivId}`);
     return [...candidates];
 }
+/**
+ * 仓储的 PDF 渲染页：浏览器能打开，后台请求却普遍被拦截。
+ *
+ * 实测 `europepmc.org/articles/...?pdf=render` 返回 403 Cloudflare 页、
+ * `ncbi.nlm.nih.gov/pmc/articles/.../pdf/` 返回 200 但内容是 HTML 落地页。
+ * 它们仍保留为最后兜底，但必须排在所有静态直链与 Unpaywall 结果之后。
+ */
+export function isPdfRenderUrl(url) {
+    return url.startsWith(`${EPMC_ARTICLE}/`) || url.startsWith(`${PMC_ARTICLE}/`);
+}
+/**
+ * 部分开放获取出版商的固定 PDF 地址规则。
+ *
+ * Europe PMC / PMC 的渲染页会对后台请求启用 Cloudflare 人机验证（浏览器能打开、
+ * Host 下载却拿到 HTML），因此优先补一条出版商原生 PDF 地址。
+ */
+function publisherPdfUrl(doi) {
+    const value = doi.trim();
+    if (value === '')
+        return null;
+    // BMC / SpringerOpen：https://link.springer.com/content/pdf/<doi>.pdf
+    if (value.startsWith('10.1186/') || value.startsWith('10.1007/')) {
+        return `https://link.springer.com/content/pdf/${encodeURI(value)}.pdf`;
+    }
+    // Frontiers：https://www.frontiersin.org/articles/<doi>/pdf
+    if (value.startsWith('10.3389/')) {
+        return `https://www.frontiersin.org/articles/${encodeURI(value)}/pdf`;
+    }
+    // PLOS ONE
+    if (value.startsWith('10.1371/journal.pone.')) {
+        return `https://journals.plos.org/plosone/article/file?id=${encodeURI(value)}&type=printable`;
+    }
+    // Nature 系列（开放获取文章可下载，订阅文章会落到 HTML 页并继续尝试其它候选）
+    if (value.startsWith('10.1038/')) {
+        return `https://www.nature.com/articles/${encodeURI(value.slice('10.1038/'.length))}.pdf`;
+    }
+    return null;
+}
 /** Europe PMC 的全文 XML 地址；没有 PMCID 时返回 null。 */
 export function epmcXmlUrl(paper) {
     const pmcid = normalizePmcid(paper.ids.pmcid);
@@ -43,13 +84,19 @@ export async function unpaywallPdfCandidates(doi, email, timeoutMs, signal) {
         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 !== '')
+        const locations = [best, ...asArray(body['oa_locations']).map(asRecord)];
+        for (const location of locations) {
+            const pdf = asString(location['url_for_pdf']);
+            if (pdf !== '') {
                 urls.add(pdf);
+                continue;
+            }
+            // 少数仓储只给 `url`，且本身就是 PDF 直链；只收明显是 PDF 的地址，
+            // 避免把落地页塞进候选后又被判成「返回内容不是 PDF」。
+            const landing = asString(location['url']);
+            if (/\.pdf(?:[?#]|$)/iu.test(landing) || /\/pdf\/(?:[?#]|$)/iu.test(landing)) {
+                urls.add(landing);
+            }
         }
         return [...urls];
     }

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

@@ -0,0 +1,12 @@
+/**
+ * Google Scholar provider —— 通过 SerpAPI 的 `google_scholar` 引擎检索。
+ *
+ * Google 不提供官方 Scholar API，且禁止程序化抓取；这里只走第三方 SerpAPI，
+ * 由用户自备 Key。未配置 Key 时直接按「限流跳过」处理，不发起请求，也不计入
+ * 失败。文档见 `docs/谷歌学术接入调研.md`。
+ *
+ * 限制：SerpAPI 单页最多 20 条，`limit > 20` 时按 `start` 翻页；结果普遍不带
+ * DOI/PMID，跨源去重主要依赖规范化标题键。
+ */
+import type { Provider } from '../types.js';
+export declare const googlescholar: Provider;

package/lib/search/providers/googlescholar.js

@@ -0,0 +1,154 @@
+/**
+ * Google Scholar provider —— 通过 SerpAPI 的 `google_scholar` 引擎检索。
+ *
+ * Google 不提供官方 Scholar API，且禁止程序化抓取；这里只走第三方 SerpAPI，
+ * 由用户自备 Key。未配置 Key 时直接按「限流跳过」处理，不发起请求，也不计入
+ * 失败。文档见 `docs/谷歌学术接入调研.md`。
+ *
+ * 限制：SerpAPI 单页最多 20 条，`limit > 20` 时按 `start` 翻页；结果普遍不带
+ * DOI/PMID，跨源去重主要依赖规范化标题键。
+ */
+import { SearchError } from '../errors.js';
+import { asArray, asNumber, asRecord, asString, normalizeDoi } from '../normalize.js';
+import { limitedJson, SourceSkipped } from '../rate-limit.js';
+const ENDPOINT = 'https://serpapi.com/search.json';
+/** SerpAPI 允许的单页条数上限。 */
+const PAGE_SIZE = 20;
+export const googlescholar = {
+    info: {
+        id: 'googlescholar',
+        label: 'Google Scholar',
+        homepage: 'https://scholar.google.com',
+        capabilities: { abstract: true, citationCount: true, openAccess: true, pdf: true },
+        rateLimit: '1 req/s 自限；受 SerpAPI 套餐配额约束（免费 250 次/月）',
+        syntax: '自然语言；支持引号短语、author:/source:，不解析 PubMed 字段标签',
+        optionalKey: true,
+    },
+    async search(query, options) {
+        const apiKey = options.serpApiKey?.trim() ?? '';
+        if (apiKey === '') {
+            throw new SourceSkipped('未配置 SerpAPI 密钥，Google Scholar 已跳过');
+        }
+        const records = [];
+        const seen = new Set();
+        for (let start = 0; start < options.limit; start += PAGE_SIZE) {
+            const num = Math.min(PAGE_SIZE, options.limit - start);
+            const params = new URLSearchParams({
+                engine: 'google_scholar',
+                q: query,
+                num: String(num),
+                start: String(start),
+                hl: 'en',
+                api_key: apiKey,
+            });
+            if (options.yearFrom !== undefined)
+                params.set('as_ylo', String(options.yearFrom));
+            if (options.yearTo !== undefined)
+                params.set('as_yhi', String(options.yearTo));
+            const payload = await limitedJson('googlescholar', `${ENDPOINT}?${params.toString()}`, {
+                timeoutMs: options.timeoutMs,
+                signal: options.signal,
+                bypassCooldown: options.bypassCooldown === true,
+                headers: { accept: 'application/json' },
+            }).catch((error) => {
+                if (error instanceof SearchError && (error.status === 401 || error.status === 403)) {
+                    throw new SearchError('upstream_error', 'SerpAPI 密钥无效或无权限，请在设置页检查');
+                }
+                throw error;
+            });
+            const response = asRecord(payload);
+            const error = asString(response['error']).trim();
+            if (error !== '') {
+                throw new SearchError('upstream_error', `SerpAPI：${error}`);
+            }
+            const items = asArray(response['organic_results']);
+            for (const item of items) {
+                const record = mapItem(item);
+                if (record.title === '')
+                    continue;
+                const key = record.sourceId === '' ? record.title : record.sourceId;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                records.push(record);
+            }
+            // 上游返回不足一页，说明没有更多结果。
+            if (items.length < num)
+                break;
+        }
+        return records;
+    },
+};
+function mapItem(raw) {
+    const item = asRecord(raw);
+    const publication = asRecord(item['publication_info']);
+    const inline = asRecord(item['inline_links']);
+    const versions = asRecord(inline['versions']);
+    const citedBy = asRecord(inline['cited_by']);
+    const title = asString(item['title']).trim();
+    const link = asString(item['link']).trim();
+    const summary = asString(publication['summary']).trim();
+    const clusterId = asString(versions['cluster_id']).trim();
+    const resultId = asString(item['result_id']).trim();
+    const doi = readDoi(link);
+    const pdfUrl = readPdfUrl(item['resources']);
+    return {
+        source: 'googlescholar',
+        sourceId: clusterId !== '' ? clusterId : resultId !== '' ? resultId : link,
+        ids: { doi, pmid: '', pmcid: '', arxivId: '' },
+        title,
+        authors: readAuthors(publication['authors'], summary),
+        year: readYear(summary),
+        venue: readVenue(summary),
+        doi,
+        url: link,
+        abstract: asString(item['snippet']).trim(),
+        citedBy: asNumber(citedBy['total']),
+        openAccess: pdfUrl !== '',
+        pdfUrl,
+        type: '',
+    };
+}
+/** 结果页不直接给 DOI；只有链接里出现 DOI 时才提取，避免误判普通 URL。 */
+function readDoi(link) {
+    if (!/10\.\d{4,9}\//u.test(link))
+        return '';
+    const match = /10\.\d{4,9}\/[^\s"<>]+/u.exec(link);
+    return match === null ? '' : normalizeDoi(match[0]);
+}
+function readPdfUrl(value) {
+    for (const entry of asArray(value)) {
+        const resource = asRecord(entry);
+        if (asString(resource['file_format']).toUpperCase() !== 'PDF')
+            continue;
+        const link = asString(resource['link']).trim();
+        if (link !== '')
+            return link;
+    }
+    return '';
+}
+function readAuthors(value, summary) {
+    const names = asArray(value)
+        .map((entry) => asString(asRecord(entry)['name']).trim())
+        .filter((name) => name !== '');
+    if (names.length > 0)
+        return names;
+    // 兜底：summary 形如「作者列表 - 标题, 年份 - 来源」。
+    const head = summary.split(' - ')[0] ?? '';
+    return head
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name !== '' && name.length <= 80);
+}
+/** summary 中的最后一个四位年份即出版年（标题里的年份通常更早）。 */
+function readYear(summary) {
+    const matches = [...summary.matchAll(/\b(?:19|20)\d{2}\b/gu)];
+    if (matches.length === 0)
+        return null;
+    return asNumber(Number(matches[matches.length - 1][0]));
+}
+/** summary 末段通常是来源站点（如 `cabdirect.org`）。 */
+function readVenue(summary) {
+    const parts = summary.split(' - ');
+    return parts.length < 2 ? '' : (parts[parts.length - 1] ?? '').trim();
+}

package/lib/search/providers/index.js

@@ -8,6 +8,7 @@ import { SOURCE_IDS } from '../types.js';
 import { arxiv } from './arxiv.js';
 import { crossref } from './crossref.js';
 import { europepmc } from './europepmc.js';
+import { googlescholar } from './googlescholar.js';
 import { openalex } from './openalex.js';
 import { pubmed } from './pubmed.js';
 import { pubtator } from './pubtator.js';
@@ -20,6 +21,7 @@ export const PROVIDERS = {
     semanticscholar,
     arxiv,
     pubtator,
+    googlescholar,
 };
 /** 注册顺序即聚合展示顺序。 */
 export const PROVIDER_INFOS = SOURCE_IDS.map((id) => PROVIDERS[id].info);

package/lib/search/query-adapter.js

@@ -22,6 +22,9 @@ export function adaptQuery(source, block) {
             return toArxivQuery(text);
         case 'pubtator':
             return toPlainText(text);
+        case 'googlescholar':
+            // 支持引号短语与 author:/source:，但不认 PubMed 字段标签与布尔式。
+            return toPlainText(text);
     }
 }
 /** 去掉 `[tiab]` 一类字段标签与通配符，保留引号短语与布尔词。 */

package/lib/search/rate-limit.js

@@ -11,7 +11,7 @@
  * - 连续成功若干次后间隔逐步回落；超时 / 临时网络故障也重试一次。
  * - 诊断探活（bypassCooldown）忽略冷却，429 仍按原始错误返回，便于定位。
  */
-import { DEFAULT_ARXIV_INTERVAL_MS, DEFAULT_PUBMED_INTERVAL_MS, DEFAULT_S2_INTERVAL_MS, getSettings, } from './config.js';
+import { DEFAULT_ARXIV_INTERVAL_MS, DEFAULT_PUBMED_INTERVAL_MS, DEFAULT_S2_INTERVAL_MS, DEFAULT_SERPAPI_INTERVAL_MS, getSettings, } from './config.js';
 import { SearchError } from './errors.js';
 import { cooldownUntil, recordSourceCooldown, recordSourceError, recordSourceOk, } from './health.js';
 import { fetchJson, fetchText } from './http.js';
@@ -23,6 +23,7 @@ const BASE_INTERVALS = {
     semanticscholar: DEFAULT_S2_INTERVAL_MS,
     arxiv: DEFAULT_ARXIV_INTERVAL_MS,
     pubtator: 350,
+    googlescholar: DEFAULT_SERPAPI_INTERVAL_MS,
 };
 /** 429 未带 Retry-After 时的冷却时长（原为 30s，过久会拖垮多检索式任务）。 */
 const COOLDOWN_FALLBACK_MS = 10_000;

package/lib/search/types.d.ts

@@ -3,13 +3,20 @@
  *
  * 本文件同时被 Host 与 Client 引用，因此不得引入任何 Node 内置模块。
  */
-/** 已接入的免费数据源 id；顺序即聚合展示顺序。 */
-export declare const SOURCE_IDS: readonly ["pubmed", "europepmc", "openalex", "crossref", "semanticscholar", "arxiv", "pubtator"];
+/**
+ * 已接入的数据源 id；顺序即聚合展示顺序。
+ *
+ * 除 `googlescholar` 外均为免费公开 API；`googlescholar` 依赖用户自备的
+ * SerpAPI Key，未配置时默认不参与检索。
+ */
+export declare const SOURCE_IDS: readonly ["pubmed", "europepmc", "openalex", "crossref", "semanticscholar", "arxiv", "pubtator", "googlescholar"];
 export type SourceId = (typeof SOURCE_IDS)[number];
 /** 排序方式。 */
 export type SortMode = 'relevance' | 'citations' | 'year';
-/** 语言筛选。 */
-export type TaskLanguage = 'any' | 'eng' | 'chi';
+/** 语言筛选；取值沿用 PubMed 的三字母语言码。 */
+export type TaskLanguage = 'any' | 'eng' | 'chi' | 'jpn' | 'kor' | 'fre' | 'ger' | 'spa' | 'rus' | 'ita' | 'por';
+/** 语言候选项；顺序即下拉与胶囊的展示顺序。 */
+export declare const TASK_LANGUAGES: readonly TaskLanguage[];
 /** 论文的持久标识集合（裸值，不带 URL 前缀）。 */
 export interface PaperIds {
     doi: string;
@@ -101,6 +108,7 @@ export interface ProviderSearchOptions {
     /** 可选密钥；provider 只用于请求参数/请求头，不得写日志。 */
     ncbiApiKey?: string;
     s2ApiKey?: string;
+    serpApiKey?: string;
 }
 export interface Provider {
     info: ProviderInfo;
@@ -145,14 +153,20 @@ export interface TaskConditions {
     pageSize: number;
 }
 /** 全文获取状态；`unknown` 表示尚未尝试。 */
-export type PdfStatus = 'unknown' | 'available' | 'downloaded' | 'html-only' | 'paywalled' | 'blocked' | 'failed';
+export type PdfStatus = 'unknown' | 'available' | 'downloaded' | 'missing' | 'html-only' | 'paywalled' | 'blocked' | 'failed';
+/**
+ * PDF 下载失败的根因分类。
+ *
+ * 除了 `failed`（网络/超时/体积等程序故障）之外，其余都属于「后台拿不到、
+ * 但浏览器可能能打开」，界面按此分流，避免把订阅受限误报成功能失败。
+ */
+export type PdfFailureReason = 'no-candidate' | 'blocked' | 'paywalled' | 'not-pdf' | 'failed';
+/** 是否需要引导用户到浏览器手动保存。 */
+export declare function isManualPdfFailure(reason: PdfFailureReason | undefined): boolean;
 /** 论文级人工筛选状态。 */
 export interface PaperState {
     screening: Screening;
     groupId?: string;
-    shortlistOrder?: number;
-    note?: string;
-    tags?: string[];
     pdfStatus?: PdfStatus;
     /** 失败原因（面向用户的一句话）。 */
     pdfError?: string;
@@ -186,7 +200,7 @@ export interface TaskResult {
  * 任务内一次检索（一轮）的元数据快照。
  *
  * 只留「这一轮用什么条件、什么时候跑、跑出多少、结果如何」，**不保存文献列表**：
- * 当前结果永远是最新一轮的 `result.papers`，人工标注按 paperId 跨轮保留。
+ * 当前结果永远是最新一轮的 `result.papers`，筛读状态按 paperId 跨轮保留。
  * 历史轮次用于时间轴回看与「回填条件重跑」。
  */
 export interface SearchRound {
@@ -233,6 +247,8 @@ export interface SearchTask {
     /** 任务级研究笔记。 */
     notes: string;
     groups: TaskGroup[];
+    /** 关联的会话工作目录；PDF 默认下载到其下的 dsh-litsearch/。 */
+    workspace?: string;
     progress?: TaskProgress;
     stats: TaskStats;
     result: TaskResult;
@@ -271,6 +287,8 @@ export interface TaskDetail extends TaskSummary {
     states: Record<string, PaperState>;
     /** 建立任务时继承筛读状态的来源任务。 */
     fromTaskId?: string;
+    /** PDF 实际保存目录（供面板悬停提示）。 */
+    downloadDir?: string;
     result: {
         totalLoaded: number;
         sources: SourceStatus[];
@@ -335,7 +353,9 @@ export interface TaskStatsReport {
     byYear: YearStat[];
     byType: CountEntry[];
     byLanguage: CountEntry[];
+    /** 出现过的出处，按命中数降序；筛选项直接用这份清单（最多 500 条）。 */
     topVenues: CountEntry[];
+    /** 出现过的作者，按命中数降序；筛选项直接用这份清单（最多 500 条）。 */
     topAuthors: CountEntry[];
     metrics: {
         oaRate: number;
@@ -365,6 +385,7 @@ export interface FullTextCoverage {
     unknown: number;
     available: number;
     downloaded: number;
+    missing: number;
     htmlOnly: number;
     paywalled: number;
     blocked: number;
@@ -376,10 +397,6 @@ export interface AnnotationInput {
     screening?: Screening;
     /** `null` 表示移出分组。 */
     groupId?: string | null;
-    /** `null` 表示清除必读顺序。 */
-    shortlistOrder?: number | null;
-    note?: string;
-    tags?: string[];
     /** 全文状态由 Host 下载/同步流程写入，面板也可显示与筛选。 */
     pdfStatus?: PdfStatus;
     pdfError?: string;
@@ -395,6 +412,8 @@ export interface PdfDownloadResult {
     path?: string;
     url?: string;
     error?: string;
+    /** 失败根因；成功时缺省。 */
+    reason?: PdfFailureReason;
 }
 /** Zotero connector 探测结果。 */
 export interface ZoteroProbeResult {
@@ -436,6 +455,8 @@ export interface PaperDetail {
     paper: Paper;
     state?: PaperState;
     groups: TaskGroup[];
+    /** PDF 实际保存目录（供面板悬停提示）。 */
+    downloadDir?: string;
 }
 /** PubTator 标注的单个实体（按标识符与原文去重）。 */
 export interface PaperEntity {
@@ -537,6 +558,7 @@ export interface HealthInfo {
     keys: {
         ncbi: boolean;
         s2: boolean;
+        serpapi: boolean;
     };
     settings: {
         defaultSources: SourceId[];

package/lib/search/types.js

@@ -3,7 +3,12 @@
  *
  * 本文件同时被 Host 与 Client 引用，因此不得引入任何 Node 内置模块。
  */
-/** 已接入的免费数据源 id；顺序即聚合展示顺序。 */
+/**
+ * 已接入的数据源 id；顺序即聚合展示顺序。
+ *
+ * 除 `googlescholar` 外均为免费公开 API；`googlescholar` 依赖用户自备的
+ * SerpAPI Key，未配置时默认不参与检索。
+ */
 export const SOURCE_IDS = [
     'pubmed',
     'europepmc',
@@ -12,4 +17,23 @@ export const SOURCE_IDS = [
     'semanticscholar',
     'arxiv',
     'pubtator',
+    'googlescholar',
+];
+/** 语言候选项；顺序即下拉与胶囊的展示顺序。 */
+export const TASK_LANGUAGES = [
+    'any',
+    'eng',
+    'chi',
+    'jpn',
+    'kor',
+    'fre',
+    'ger',
+    'spa',
+    'rus',
+    'ita',
+    'por',
 ];
+/** 是否需要引导用户到浏览器手动保存。 */
+export function isManualPdfFailure(reason) {
+    return reason !== undefined && reason !== 'failed';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-litsearch",
-  "version": "0.2.0",
+  "version": "0.3.5",
   "description": "Search free scholarly literature sources from DSH. The model can search OpenAlex, Crossref and more with native tools, while you can run the same searches in a sidebar panel and send any paper into the conversation.",
   "keywords": [
     "dsh",