dsh-plugin-litsearch 0.0.0-stage → 0.2.0

package/lib/host/zotero/connector.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Zotero Connector 协议封装（本机 `http://127.0.0.1:23119`）。
+ *
+ * 只允许回环地址：connector 是桌面端本地服务，绝不把用户数据发到外部主机。
+ * 任何失败都转成可读的一句话，由调用方汇总成「未运行 / 条目保存失败 / 附件失败」。
+ */
+import type { Paper, ZoteroProbeResult, ZoteroSyncResult } from '../../search/types.js';
+export interface ZoteroConnectorOptions {
+    baseUrl: string;
+    attachPdf: boolean;
+    tag: string;
+}
+export interface ZoteroSyncInput {
+    paper: Paper;
+    tags: readonly string[];
+    /** 已下载的本地 PDF；缺省表示没有。 */
+    pdfPath?: string;
+}
+export declare class ZoteroConnector {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    probe(): Promise<ZoteroProbeResult>;
+    /** 当前 Zotero 里选中的分类；未选中时返回 null。 */
+    selectedCollection(): Promise<SelectedCollection | null>;
+    /**
+     * 保存条目并可选上传本地 PDF。
+     *
+     * 逐篇处理：单篇条目失败只记入 failed，不中断其余篇；附件失败单独计入
+     * messages，条目仍算保存成功。
+     */
+    sync(inputs: readonly ZoteroSyncInput[], options: ZoteroConnectorOptions): Promise<ZoteroSyncResult>;
+    /**
+     * 保存条目。Zotero 返回 201 空响应，条目 id 由请求里的 `id` 字段决定，
+     * 后续 `saveAttachment` 用它作为 parentItemID，并复用同一 sessionID。
+     */
+    private saveItem;
+    private saveAttachment;
+    private request;
+}
+interface SelectedCollection {
+    id: number | string;
+    name: string;
+    libraryID?: number;
+    filesEditable?: boolean;
+}
+export {};

package/lib/host/zotero/connector.js

@@ -0,0 +1,263 @@
+/**
+ * Zotero Connector 协议封装（本机 `http://127.0.0.1:23119`）。
+ *
+ * 只允许回环地址：connector 是桌面端本地服务，绝不把用户数据发到外部主机。
+ * 任何失败都转成可读的一句话，由调用方汇总成「未运行 / 条目保存失败 / 附件失败」。
+ */
+import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { isIP } from 'node:net';
+const PING_TIMEOUT_MS = 3_000;
+const SAVE_TIMEOUT_MS = 20_000;
+const ATTACH_TIMEOUT_MS = 60_000;
+const MAX_SYNC_ITEMS = 50;
+export class ZoteroConnector {
+    baseUrl;
+    constructor(baseUrl) {
+        // 允许 http://127.0.0.1:23119 / http://localhost:23119 / [::1]。
+        const trimmed = baseUrl.trim().replace(/\/+$/u, '');
+        let url;
+        try {
+            url = new URL(trimmed);
+        }
+        catch {
+            throw new Error(`Zotero 地址不合法：${baseUrl}`);
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            throw new Error('Zotero 地址只支持 http/https');
+        }
+        const host = url.hostname.replace(/^\[|\]$/gu, '').toLowerCase();
+        const loopback = host === 'localhost' ||
+            host === '::1' ||
+            (isIP(host) === 4 && host.split('.')[0] === '127');
+        if (!loopback)
+            throw new Error('Zotero connector 只监听本机，地址必须是 127.0.0.1 或 localhost');
+        this.baseUrl = trimmed;
+    }
+    async probe() {
+        try {
+            const response = await this.request('/connector/ping', {
+                method: 'GET',
+                timeoutMs: PING_TIMEOUT_MS,
+            });
+            if (!response.ok) {
+                return { ok: false, error: `connector 返回 HTTP ${response.status}` };
+            }
+            const version = response.headers.get('x-zotero-version') ?? undefined;
+            const collection = await this.selectedCollection().catch(() => null);
+            const result = { ok: true };
+            if (version !== undefined)
+                result.version = version;
+            if (collection !== null) {
+                result.collection = {
+                    id: collection.id,
+                    name: collection.name,
+                    ...(collection.libraryID === undefined ? {} : { libraryID: collection.libraryID }),
+                    ...(collection.filesEditable === undefined
+                        ? {}
+                        : { filesEditable: collection.filesEditable }),
+                };
+            }
+            return result;
+        }
+        catch (error) {
+            return { ok: false, error: describe(error) };
+        }
+    }
+    /** 当前 Zotero 里选中的分类；未选中时返回 null。 */
+    async selectedCollection() {
+        const response = await this.request('/connector/getSelectedCollection', {
+            method: 'GET',
+            timeoutMs: PING_TIMEOUT_MS,
+        });
+        if (!response.ok)
+            return null;
+        const body = (await response.json().catch(() => null));
+        if (body === null || body === false || typeof body !== 'object')
+            return null;
+        const record = body;
+        const id = record['id'];
+        const name = record['name'];
+        if ((typeof id !== 'number' && typeof id !== 'string') || typeof name !== 'string')
+            return null;
+        const collection = { id, name };
+        if (typeof record['libraryID'] === 'number')
+            collection.libraryID = record['libraryID'];
+        if (typeof record['filesEditable'] === 'boolean') {
+            collection.filesEditable = record['filesEditable'];
+        }
+        return collection;
+    }
+    /**
+     * 保存条目并可选上传本地 PDF。
+     *
+     * 逐篇处理：单篇条目失败只记入 failed，不中断其余篇；附件失败单独计入
+     * messages，条目仍算保存成功。
+     */
+    async sync(inputs, options) {
+        if (inputs.length === 0)
+            return { ok: true, saved: 0, attached: 0, failed: 0, messages: [] };
+        if (inputs.length > MAX_SYNC_ITEMS) {
+            throw new Error(`一次最多同步 ${MAX_SYNC_ITEMS} 篇`);
+        }
+        const result = {
+            ok: true,
+            saved: 0,
+            attached: 0,
+            failed: 0,
+            messages: [],
+        };
+        for (const input of inputs) {
+            const sessionID = newSessionID();
+            const item = toZoteroItem(input.paper, input.tags, options.tag);
+            try {
+                await this.saveItem(item, sessionID);
+                result.saved += 1;
+            }
+            catch (error) {
+                result.failed += 1;
+                result.messages.push(`${shortTitle(input.paper.title)}：条目保存失败（${describe(error)}）`);
+                continue;
+            }
+            if (!options.attachPdf || input.pdfPath === undefined)
+                continue;
+            const parentId = typeof item['id'] === 'string' ? item['id'] : null;
+            if (parentId === null) {
+                result.messages.push(`${shortTitle(input.paper.title)}：条目已保存，但缺少条目 id，未上传 PDF`);
+                continue;
+            }
+            try {
+                const buffer = await readFile(input.pdfPath);
+                await this.saveAttachment(parentId, sessionID, input.paper, buffer);
+                result.attached += 1;
+            }
+            catch (error) {
+                result.messages.push(`${shortTitle(input.paper.title)}：PDF 附件失败（${describe(error)}）`);
+            }
+        }
+        result.ok = result.failed === 0;
+        return result;
+    }
+    /**
+     * 保存条目。Zotero 返回 201 空响应，条目 id 由请求里的 `id` 字段决定，
+     * 后续 `saveAttachment` 用它作为 parentItemID，并复用同一 sessionID。
+     */
+    async saveItem(item, sessionID) {
+        const response = await this.request('/connector/saveItems', {
+            method: 'POST',
+            timeoutMs: SAVE_TIMEOUT_MS,
+            headers: {
+                'content-type': 'application/json',
+                'x-zotero-connector-api-version': '3',
+            },
+            body: JSON.stringify({
+                sessionID,
+                uri: `https://www.zotero.org/connector/${sessionID}`,
+                items: [item],
+            }),
+        });
+        if (!response.ok)
+            throw new Error(`connector 返回 HTTP ${response.status}`);
+    }
+    async saveAttachment(parentId, sessionID, paper, buffer) {
+        const metadata = JSON.stringify({
+            sessionID,
+            parentItemID: parentId,
+            title: attachmentFilename(paper),
+            url: paper.pdfUrl !== '' ? paper.pdfUrl : paper.url,
+        });
+        const response = await this.request('/connector/saveAttachment', {
+            method: 'POST',
+            timeoutMs: ATTACH_TIMEOUT_MS,
+            headers: {
+                'content-type': 'application/pdf',
+                'content-length': String(buffer.length),
+                'x-metadata': metadata,
+            },
+            body: Uint8Array.from(buffer),
+        });
+        if (!response.ok)
+            throw new Error(`connector 返回 HTTP ${response.status}`);
+    }
+    async request(path, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), init.timeoutMs);
+        try {
+            return await fetch(`${this.baseUrl}${path}`, {
+                method: init.method,
+                ...(init.headers === undefined ? {} : { headers: init.headers }),
+                ...(init.body === undefined ? {} : { body: init.body }),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (controller.signal.aborted) {
+                throw new Error('连接超时；请确认 Zotero 正在运行且已开启 connector 服务');
+            }
+            throw new Error(`无法连接 Zotero（${this.baseUrl}）；请确认 Zotero 桌面端已启动并允许 connector`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function toZoteroItem(paper, tags, defaultTag) {
+    const item = {
+        id: paper.paperId,
+        itemType: paper.type === '' ? 'journalArticle' : mapItemType(paper.type),
+        title: paper.title,
+        creators: paper.authors.map((name) => {
+            const parts = name.trim().split(/\s+/u);
+            const lastName = parts.length > 1 ? parts.at(-1) ?? name : name;
+            const firstName = parts.length > 1 ? parts.slice(0, -1).join(' ') : '';
+            return { creatorType: 'author', firstName, lastName };
+        }),
+        date: paper.year === null ? '' : String(paper.year),
+        publicationTitle: paper.venue,
+        DOI: paper.doi,
+        url: paper.url,
+        abstractNote: paper.abstract,
+        extra: `dsh-litsearch:${paper.paperId}`,
+    };
+    const merged = new Set();
+    for (const tag of [...tags, defaultTag]) {
+        const value = tag.trim();
+        if (value !== '')
+            merged.add(value);
+    }
+    if (merged.size > 0)
+        item['tags'] = [...merged].map((tag) => ({ tag }));
+    return item;
+}
+function mapItemType(type) {
+    const value = type.toLowerCase();
+    if (value.includes('review'))
+        return 'journalArticle';
+    if (value.includes('preprint') || value.includes('arxiv'))
+        return 'preprint';
+    if (value.includes('conference') || value.includes('proceedings'))
+        return 'conferencePaper';
+    if (value.includes('book'))
+        return 'book';
+    if (value.includes('dataset'))
+        return 'dataset';
+    return 'journalArticle';
+}
+function newSessionID() {
+    return randomUUID().replace(/-/gu, '').slice(0, 16);
+}
+function attachmentFilename(paper) {
+    const base = paper.title
+        .normalize('NFKC')
+        .replace(/[\\/:*?"<>|\r\n]+/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, 80);
+    return `${base === '' ? paper.paperId : base}.pdf`;
+}
+function shortTitle(title) {
+    return title.length > 40 ? `${title.slice(0, 40)}…` : title;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * dsh-plugin-litsearch —— 插件入口（Host 半）。
+ *
+ * 做三件事：
+ * 1. 导出 Schemastery `Config`（逐字段 `.volatile()`），让 dsh「设置中心」能
+ *    渲染「文献检索」页；保存后无需重启即生效。
+ * 2. 装配 `TaskService`（任务持久化 / 执行 / 事件），并把检索能力注册进 dsh
+ *    工具表（`literature_search` / `literature_sources`）。
+ * 3. 在宿主 web server 上注册 `/dsh-litsearch/api/*` 端点，供右侧栏面板与
+ *    设置页取数。
+ *
+ * `webServer` / `tools` 的类型不在已安装的 dsh 包里，因此自定义最小结构接口并
+ * 强转（与 dsh-plugin-zotero 同法）。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+export declare const name = "dsh-plugin-litsearch";
+/**
+ * 插件配置 schema（逐字段 volatile）。
+ *
+ * volatile 是 dsh 配置表单的硬前提；用 `.volatile()` 后保存只提交新值并
+ * 唤醒引用，条目本身不重挂，因此改配置无需重启 dsh。
+ */
+export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+    /** 作为 OpenAlex / Crossref / NCBI 的联系邮箱；留空也可用。 */
+    contactEmail: Schema<string, string, "volatile-defined">;
+    /** 可选 NCBI API Key（E-utilities 额度从 3 req/s 提升到 10 req/s）。 */
+    ncbiApiKey: Schema<string, string, "volatile-defined">;
+    /** 可选 Semantic Scholar API Key。 */
+    s2ApiKey: Schema<string, string, "volatile-defined">;
+    /** 各源最小请求间隔（毫秒）。 */
+    pubmedIntervalMs: Schema<number, number, "volatile-defined">;
+    s2IntervalMs: Schema<number, number, "volatile-defined">;
+    arxivIntervalMs: Schema<number, number, "volatile-defined">;
+    /** 默认每次加载条数。 */
+    defaultPageSize: Schema<number, number, "volatile-defined">;
+    /** 单次上游请求超时（毫秒）。 */
+    requestTimeoutMs: Schema<number, number, "volatile-defined">;
+    /** 默认数据源。 */
+    defaultSources: Schema<NoInfer<("pubmed" | "europepmc" | "openalex" | "crossref" | "semanticscholar" | "arxiv" | "pubtator")[]>, NoInfer<("pubmed" | "europepmc" | "openalex" | "crossref" | "semanticscholar" | "arxiv" | "pubtator")[]>, "volatile-defined">;
+    defaultSort: Schema<"relevance" | "citations" | "year", "relevance" | "citations" | "year", "volatile-defined">;
+    defaultLanguage: Schema<"any" | "eng" | "chi", "any" | "eng" | "chi", "volatile-defined">;
+    /** 模型发起检索后是否自动打开任务 tab。 */
+    autoOpenTaskTab: Schema<boolean, boolean, "volatile-defined">;
+    /** 同时保留的任务 tab 上限。 */
+    maxTaskTabs: Schema<number, number, "volatile-defined">;
+    /** 任务保留天数与条数（置顶任务不受限）。 */
+    taskRetentionDays: Schema<number, number, "volatile-defined">;
+    taskRetentionCount: Schema<number, number, "volatile-defined">;
+    /** 单任务结果上限。 */
+    taskMaxPapers: Schema<number, number, "volatile-defined">;
+    /** PDF 下载根目录。 */
+    pdfRoot: Schema<string, string, "volatile-defined">;
+    /** 单个 PDF 最大体积（MB）。 */
+    pdfMaxMb: Schema<number, number, "volatile-defined">;
+    /** 检索完成后自动下载缺失 PDF。 */
+    autoDownloadPdf: Schema<boolean, boolean, "volatile-defined">;
+    /** 无 PDF 时用 Europe PMC HTML 全文兜底。 */
+    enableEpmcFulltext: Schema<boolean, boolean, "volatile-defined">;
+    /** Zotero 入口开关。 */
+    zoteroEnabled: Schema<boolean, boolean, "volatile-defined">;
+    zoteroBaseUrl: Schema<string, string, "volatile-defined">;
+    zoteroAttachPdf: Schema<boolean, boolean, "volatile-defined">;
+    zoteroTag: Schema<string, string, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    /** 作为 OpenAlex / Crossref / NCBI 的联系邮箱；留空也可用。 */
+    contactEmail: Schema<string, string, "volatile-defined">;
+    /** 可选 NCBI API Key（E-utilities 额度从 3 req/s 提升到 10 req/s）。 */
+    ncbiApiKey: Schema<string, string, "volatile-defined">;
+    /** 可选 Semantic Scholar API Key。 */
+    s2ApiKey: Schema<string, string, "volatile-defined">;
+    /** 各源最小请求间隔（毫秒）。 */
+    pubmedIntervalMs: Schema<number, number, "volatile-defined">;
+    s2IntervalMs: Schema<number, number, "volatile-defined">;
+    arxivIntervalMs: Schema<number, number, "volatile-defined">;
+    /** 默认每次加载条数。 */
+    defaultPageSize: Schema<number, number, "volatile-defined">;
+    /** 单次上游请求超时（毫秒）。 */
+    requestTimeoutMs: Schema<number, number, "volatile-defined">;
+    /** 默认数据源。 */
+    defaultSources: Schema<NoInfer<("pubmed" | "europepmc" | "openalex" | "crossref" | "semanticscholar" | "arxiv" | "pubtator")[]>, NoInfer<("pubmed" | "europepmc" | "openalex" | "crossref" | "semanticscholar" | "arxiv" | "pubtator")[]>, "volatile-defined">;
+    defaultSort: Schema<"relevance" | "citations" | "year", "relevance" | "citations" | "year", "volatile-defined">;
+    defaultLanguage: Schema<"any" | "eng" | "chi", "any" | "eng" | "chi", "volatile-defined">;
+    /** 模型发起检索后是否自动打开任务 tab。 */
+    autoOpenTaskTab: Schema<boolean, boolean, "volatile-defined">;
+    /** 同时保留的任务 tab 上限。 */
+    maxTaskTabs: Schema<number, number, "volatile-defined">;
+    /** 任务保留天数与条数（置顶任务不受限）。 */
+    taskRetentionDays: Schema<number, number, "volatile-defined">;
+    taskRetentionCount: Schema<number, number, "volatile-defined">;
+    /** 单任务结果上限。 */
+    taskMaxPapers: Schema<number, number, "volatile-defined">;
+    /** PDF 下载根目录。 */
+    pdfRoot: Schema<string, string, "volatile-defined">;
+    /** 单个 PDF 最大体积（MB）。 */
+    pdfMaxMb: Schema<number, number, "volatile-defined">;
+    /** 检索完成后自动下载缺失 PDF。 */
+    autoDownloadPdf: Schema<boolean, boolean, "volatile-defined">;
+    /** 无 PDF 时用 Europe PMC HTML 全文兜底。 */
+    enableEpmcFulltext: Schema<boolean, boolean, "volatile-defined">;
+    /** Zotero 入口开关。 */
+    zoteroEnabled: Schema<boolean, boolean, "volatile-defined">;
+    zoteroBaseUrl: Schema<string, string, "volatile-defined">;
+    zoteroAttachPdf: Schema<boolean, boolean, "volatile-defined">;
+    zoteroTag: Schema<string, string, "volatile-defined">;
+}>>, "plain">;
+export declare function apply(ctx: Context, config: Schemastery.TypeT<typeof Config>): void;

package/lib/index.js

@@ -0,0 +1,153 @@
+/**
+ * dsh-plugin-litsearch —— 插件入口（Host 半）。
+ *
+ * 做三件事：
+ * 1. 导出 Schemastery `Config`（逐字段 `.volatile()`），让 dsh「设置中心」能
+ *    渲染「文献检索」页；保存后无需重启即生效。
+ * 2. 装配 `TaskService`（任务持久化 / 执行 / 事件），并把检索能力注册进 dsh
+ *    工具表（`literature_search` / `literature_sources`）。
+ * 3. 在宿主 web server 上注册 `/dsh-litsearch/api/*` 端点，供右侧栏面板与
+ *    设置页取数。
+ *
+ * `webServer` / `tools` 的类型不在已安装的 dsh 包里，因此自定义最小结构接口并
+ * 强转（与 dsh-plugin-zotero 同法）。
+ */
+import Schema from '@deepseek-ai/schemastery';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createHandler } from './host/router.js';
+import { literatureTools } from './host/tools.js';
+import { TaskService } from './host/tasks/service.js';
+import { DEFAULT_ARXIV_INTERVAL_MS, DEFAULT_AUTO_DOWNLOAD_PDF, DEFAULT_AUTO_OPEN, DEFAULT_ENABLE_EPMC_FULLTEXT, DEFAULT_LANGUAGE, DEFAULT_MAX_TASK_TABS, DEFAULT_PAGE_SIZE, DEFAULT_PDF_MAX_MB, DEFAULT_PUBMED_INTERVAL_MS, DEFAULT_RETENTION_COUNT, DEFAULT_RETENTION_DAYS, DEFAULT_S2_INTERVAL_MS, DEFAULT_SORT, DEFAULT_TASK_MAX_PAPERS, DEFAULT_ZOTERO_ATTACH_PDF, DEFAULT_ZOTERO_BASE_URL, DEFAULT_ZOTERO_ENABLED, DEFAULT_ZOTERO_TAG, MAX_LIMIT, REQUEST_TIMEOUT_MS, ROUTE_MATCH, setSettingsReader, } from './search/config.js';
+import { SOURCE_IDS } from './search/types.js';
+export const name = 'dsh-plugin-litsearch';
+/**
+ * 插件配置 schema（逐字段 volatile）。
+ *
+ * volatile 是 dsh 配置表单的硬前提；用 `.volatile()` 后保存只提交新值并
+ * 唤醒引用，条目本身不重挂，因此改配置无需重启 dsh。
+ */
+export const Config = Schema.object({
+    /** 作为 OpenAlex / Crossref / NCBI 的联系邮箱；留空也可用。 */
+    contactEmail: Schema.string().default('').volatile(),
+    /** 可选 NCBI API Key（E-utilities 额度从 3 req/s 提升到 10 req/s）。 */
+    ncbiApiKey: Schema.string().default('').role('secret').volatile(),
+    /** 可选 Semantic Scholar API Key。 */
+    s2ApiKey: Schema.string().default('').role('secret').volatile(),
+    /** 各源最小请求间隔（毫秒）。 */
+    pubmedIntervalMs: Schema.number().default(DEFAULT_PUBMED_INTERVAL_MS).volatile(),
+    s2IntervalMs: Schema.number().default(DEFAULT_S2_INTERVAL_MS).volatile(),
+    arxivIntervalMs: Schema.number().default(DEFAULT_ARXIV_INTERVAL_MS).volatile(),
+    /** 默认每次加载条数。 */
+    defaultPageSize: Schema.number().default(DEFAULT_PAGE_SIZE).volatile(),
+    /** 单次上游请求超时（毫秒）。 */
+    requestTimeoutMs: Schema.number().default(REQUEST_TIMEOUT_MS).volatile(),
+    /** 默认数据源。 */
+    defaultSources: Schema.array(Schema.union([
+        Schema.const('pubmed'),
+        Schema.const('europepmc'),
+        Schema.const('openalex'),
+        Schema.const('crossref'),
+        Schema.const('semanticscholar'),
+        Schema.const('arxiv'),
+        Schema.const('pubtator'),
+    ]))
+        .default([...SOURCE_IDS])
+        .volatile(),
+    defaultSort: Schema.union([
+        Schema.const('relevance'),
+        Schema.const('citations'),
+        Schema.const('year'),
+    ])
+        .default(DEFAULT_SORT)
+        .volatile(),
+    defaultLanguage: Schema.union([Schema.const('any'), Schema.const('eng'), Schema.const('chi')])
+        .default(DEFAULT_LANGUAGE)
+        .volatile(),
+    /** 模型发起检索后是否自动打开任务 tab。 */
+    autoOpenTaskTab: Schema.boolean().default(DEFAULT_AUTO_OPEN).volatile(),
+    /** 同时保留的任务 tab 上限。 */
+    maxTaskTabs: Schema.number().default(DEFAULT_MAX_TASK_TABS).volatile(),
+    /** 任务保留天数与条数（置顶任务不受限）。 */
+    taskRetentionDays: Schema.number().default(DEFAULT_RETENTION_DAYS).volatile(),
+    taskRetentionCount: Schema.number().default(DEFAULT_RETENTION_COUNT).volatile(),
+    /** 单任务结果上限。 */
+    taskMaxPapers: Schema.number().default(DEFAULT_TASK_MAX_PAPERS).volatile(),
+    /** PDF 下载根目录。 */
+    pdfRoot: Schema.string().default(join(homedir(), 'Downloads', 'dsh-litsearch')).volatile(),
+    /** 单个 PDF 最大体积（MB）。 */
+    pdfMaxMb: Schema.number().default(DEFAULT_PDF_MAX_MB).volatile(),
+    /** 检索完成后自动下载缺失 PDF。 */
+    autoDownloadPdf: Schema.boolean().default(DEFAULT_AUTO_DOWNLOAD_PDF).volatile(),
+    /** 无 PDF 时用 Europe PMC HTML 全文兜底。 */
+    enableEpmcFulltext: Schema.boolean().default(DEFAULT_ENABLE_EPMC_FULLTEXT).volatile(),
+    /** Zotero 入口开关。 */
+    zoteroEnabled: Schema.boolean().default(DEFAULT_ZOTERO_ENABLED).volatile(),
+    zoteroBaseUrl: Schema.string().default(DEFAULT_ZOTERO_BASE_URL).volatile(),
+    zoteroAttachPdf: Schema.boolean().default(DEFAULT_ZOTERO_ATTACH_PDF).volatile(),
+    zoteroTag: Schema.string().default(DEFAULT_ZOTERO_TAG).volatile(),
+});
+export function apply(ctx, config) {
+    // 每次读取都走 volatile 引用，始终拿到最新值。
+    setSettingsReader(() => ({
+        contactEmail: config.contactEmail.get().trim(),
+        ncbiApiKey: config.ncbiApiKey.get().trim(),
+        s2ApiKey: config.s2ApiKey.get().trim(),
+        pubmedIntervalMs: clampInt(config.pubmedIntervalMs.get(), 50, 10_000, DEFAULT_PUBMED_INTERVAL_MS),
+        s2IntervalMs: clampInt(config.s2IntervalMs.get(), 50, 60_000, DEFAULT_S2_INTERVAL_MS),
+        arxivIntervalMs: clampInt(config.arxivIntervalMs.get(), 50, 60_000, DEFAULT_ARXIV_INTERVAL_MS),
+        defaultPageSize: clampInt(config.defaultPageSize.get(), 1, MAX_LIMIT, DEFAULT_PAGE_SIZE),
+        requestTimeoutMs: clampInt(config.requestTimeoutMs.get(), 1_000, 120_000, REQUEST_TIMEOUT_MS),
+        defaultSources: normalizeSources(config.defaultSources.get()),
+        defaultSort: normalizeSort(config.defaultSort.get()),
+        defaultLanguage: normalizeLanguage(config.defaultLanguage.get()),
+        autoOpenTaskTab: config.autoOpenTaskTab.get(),
+        maxTaskTabs: clampInt(config.maxTaskTabs.get(), 1, 20, DEFAULT_MAX_TASK_TABS),
+        taskRetentionDays: clampInt(config.taskRetentionDays.get(), 1, 3_650, DEFAULT_RETENTION_DAYS),
+        taskRetentionCount: clampInt(config.taskRetentionCount.get(), 1, 10_000, DEFAULT_RETENTION_COUNT),
+        taskMaxPapers: clampInt(config.taskMaxPapers.get(), 10, 10_000, DEFAULT_TASK_MAX_PAPERS),
+        pdfRoot: config.pdfRoot.get().trim(),
+        pdfMaxMb: clampInt(config.pdfMaxMb.get(), 1, 200, DEFAULT_PDF_MAX_MB),
+        autoDownloadPdf: config.autoDownloadPdf.get(),
+        enableEpmcFulltext: config.enableEpmcFulltext.get(),
+        zoteroEnabled: config.zoteroEnabled.get(),
+        zoteroBaseUrl: normalizeBaseUrl(config.zoteroBaseUrl.get()),
+        zoteroAttachPdf: config.zoteroAttachPdf.get(),
+        zoteroTag: config.zoteroTag.get().trim().slice(0, 40) || DEFAULT_ZOTERO_TAG,
+    }));
+    // 任务状态是模型工具与 HTTP 路由的唯一事实源。
+    const service = new TaskService();
+    ctx.effect(() => () => service.dispose(), 'dsh-plugin-litsearch: task service');
+    // 模型侧：原生注册，不依赖外部 MCP。
+    ctx.inject(['tools'], (toolCtx) => {
+        const toolsService = toolCtx.tools;
+        for (const definition of literatureTools(service)) {
+            toolCtx.effect(() => toolsService.register(definition), `dsh-plugin-litsearch: ${definition.name}`);
+        }
+    });
+    // 人侧：右侧栏面板与设置页通过回环端点读写任务。
+    ctx.inject(['webServer'], (hostCtx) => {
+        const webServer = hostCtx.webServer;
+        const handler = createHandler(service);
+        hostCtx.effect(() => webServer.register({ kind: 'prefix', path: ROUTE_MATCH, handler }), 'dsh-plugin-litsearch: http routes');
+    });
+}
+function clampInt(value, min, max, fallback) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(Math.max(Math.floor(value), min), max);
+}
+function normalizeSources(value) {
+    const valid = SOURCE_IDS.filter((id) => value.includes(id));
+    return valid.length === 0 ? [...SOURCE_IDS] : valid;
+}
+function normalizeSort(value) {
+    return value === 'citations' || value === 'year' ? value : 'relevance';
+}
+function normalizeLanguage(value) {
+    return value === 'eng' || value === 'chi' ? value : 'any';
+}
+function normalizeBaseUrl(value) {
+    const trimmed = value.trim().replace(/\/+$/u, '');
+    return /^https?:\/\//u.test(trimmed) ? trimmed : DEFAULT_ZOTERO_BASE_URL;
+}

package/lib/search/aggregate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 多源检索扇出。
+ *
+ * 一次调用只跑一条检索式：并发请求选中的数据源，用 `allSettled` 隔离单源
+ * 故障，返回逐源的命中记录与状态。跨源去重、身份合并与排序交给 `identity.ts`，
+ * 任务执行器负责把多条检索式的结果拼在一起。
+ */
+import type { PaperRecord, SearchOptions, SourceId } from './types.js';
+export interface SourceRunResult {
+    source: SourceId;
+    ok: boolean;
+    records: PaperRecord[];
+    error?: string;
+    /** 因遵守上游限流而跳过；不是失败，不计入 partial 与红色报错。 */
+    skipped?: boolean;
+}
+export declare function searchSources(options: SearchOptions): Promise<SourceRunResult[]>;

package/lib/search/aggregate.js

@@ -0,0 +1,60 @@
+/**
+ * 多源检索扇出。
+ *
+ * 一次调用只跑一条检索式：并发请求选中的数据源，用 `allSettled` 隔离单源
+ * 故障，返回逐源的命中记录与状态。跨源去重、身份合并与排序交给 `identity.ts`，
+ * 任务执行器负责把多条检索式的结果拼在一起。
+ */
+import { MAX_LIMIT, getSettings } from './config.js';
+import { SearchError } from './errors.js';
+import { PROVIDERS, resolveSources } from './providers/index.js';
+import { adaptQuery } from './query-adapter.js';
+import { SourceSkipped } from './rate-limit.js';
+export async function searchSources(options) {
+    const query = options.query.trim();
+    if (query === '')
+        throw new SearchError('bad_request', '检索关键词不能为空');
+    if (options.yearFrom !== undefined &&
+        options.yearTo !== undefined &&
+        options.yearFrom > options.yearTo) {
+        throw new SearchError('bad_request', '起始年份不能晚于结束年份');
+    }
+    const settings = getSettings();
+    const limit = clampLimit(options.limit, settings.defaultPageSize);
+    const sources = resolveSources(options.sources);
+    const contactEmail = options.contactEmail !== '' ? options.contactEmail : settings.contactEmail;
+    const timeoutMs = options.timeoutMs > 0 ? options.timeoutMs : settings.requestTimeoutMs;
+    const settled = await Promise.allSettled(sources.map((id) => {
+        const adapted = adaptQuery(id, { text: query, perSource: options.perSource });
+        if (adapted === '')
+            return Promise.resolve([]);
+        return PROVIDERS[id].search(adapted, {
+            limit,
+            yearFrom: options.yearFrom,
+            yearTo: options.yearTo,
+            openAccessOnly: options.openAccessOnly,
+            contactEmail,
+            timeoutMs,
+            signal: options.signal,
+            bypassCooldown: options.bypassCooldown === true,
+            ncbiApiKey: settings.ncbiApiKey,
+            s2ApiKey: settings.s2ApiKey,
+        });
+    }));
+    return settled.map((outcome, index) => {
+        const source = sources[index];
+        if (outcome.status === 'fulfilled') {
+            return { source, ok: true, records: outcome.value };
+        }
+        const reason = outcome.reason;
+        const message = reason instanceof Error ? reason.message : String(reason);
+        if (reason instanceof SourceSkipped) {
+            return { source, ok: false, records: [], skipped: true, error: message };
+        }
+        return { source, ok: false, records: [], error: message };
+    });
+}
+function clampLimit(value, fallback) {
+    const base = Number.isFinite(value) ? value : fallback;
+    return Math.min(Math.max(Math.floor(base), 1), MAX_LIMIT);
+}