dsh-plugin-litsearch 0.2.0 → 0.3.5

package/lib/host/tools.js

@@ -6,7 +6,7 @@
  *   都有效）；只有用户明确要求新任务时才新建。等待最多 25 秒后把任务头部与前
  *   若干条结果交给模型，并明确要求本轮到此为止、只给完善建议、不发起下一轮。
  * - `literature_sources`：列出已接入的数据源与能力，便于模型决定后续策略。
- * - `literature_task`：读取/修改已保存任务（含轮次历史），写入筛读、分组与备注，
+ * - `literature_task`：读取/修改已保存任务（含轮次历史），写入筛读与分组，
  *   做新老对比与统计。
  * - `literature_export`：把任务（按筛选）导出为 CSV / RIS / BibTeX / Markdown 并落盘。
  *
@@ -16,7 +16,8 @@ import { MAX_LIMIT } from '../search/config.js';
 import { SearchError } from '../search/errors.js';
 import { asRecord } from '../search/normalize.js';
 import { PROVIDER_INFOS } from '../search/providers/index.js';
-import { SOURCE_IDS } from '../search/types.js';
+import { SOURCE_IDS, TASK_LANGUAGES } from '../search/types.js';
+import { resolveSessionWorkspace } from './workspace.js';
 /** 模型侧最多等多久；超时后任务继续跑，只返回当前进度与已有结果。 */
 const MODEL_WAIT_MS = 25_000;
 /** 交给模型的条数（UI 走分页端点，不受此限制）。 */
@@ -24,7 +25,7 @@ const TOOL_PAPER_LIMIT = 10;
 /** 复用任务时，最多等多久让上一轮跑完；超时直接返回提示，绝不新建任务。 */
 const WAIT_PREVIOUS_MS = 12_000;
 const SORT_MODES = ['relevance', 'citations', 'year'];
-const LANGUAGES = ['any', 'eng', 'chi'];
+const LANGUAGES = TASK_LANGUAGES;
 const SCREENINGS = ['unread', 'read', 'included', 'excluded'];
 const EXPORT_FORMATS = ['csv', 'ris', 'bibtex', 'md'];
 const TASK_ACTIONS = [
@@ -105,7 +106,7 @@ const SEARCH_PARAMETERS = {
         sources: {
             type: 'array',
             items: { type: 'string', enum: [...SOURCE_IDS] },
-            description: `要查询的数据源：${SOURCE_IDS.join(', ')}；省略表示全部。`,
+            description: `要查询的数据源：${SOURCE_IDS.join(', ')}；省略表示默认数据源（googlescholar 需配置 SerpAPI Key，默认关闭）。`,
         },
         limit: {
             type: 'integer',
@@ -138,7 +139,7 @@ const TASK_PARAMETERS = {
         action: {
             type: 'string',
             enum: [...TASK_ACTIONS],
-            description: 'current 读「当前任务」（推荐在执行检索/任务操作前先调用，确认这个对话正在用哪个任务，无需 id）；list 列任务；get 读条件与结果；update 改条件/标题/笔记/分组；run 重跑（仅在用户明确要求进入下一轮时使用）；rounds 读该任务的检索轮次历史；annotate 写筛读/备注；compare 与旧任务对比；stats 读语料统计。',
+            description: 'current 读「当前任务」（推荐在执行检索/任务操作前先调用，确认这个对话正在用哪个任务，无需 id）；list 列任务；get 读条件与结果；update 改条件/标题/笔记/分组；run 重跑（仅在用户明确要求进入下一轮时使用）；rounds 读该任务的检索轮次历史；annotate 写筛读/分组；compare 与旧任务对比；stats 读语料统计。',
         },
         id: { type: 'string', description: '任务 id；除 current / list 外必填。' },
         withTaskId: { type: 'string', description: 'compare 时的基准任务 id。' },
@@ -200,16 +201,13 @@ const TASK_PARAMETERS = {
         papers: {
             type: 'array',
             maxItems: 50,
-            description: 'annotate 时的逐篇写入（筛读 / 分组 / 必读顺序 / 备注 / 标签）。',
+            description: 'annotate 时的逐篇写入（筛读 / 分组）。',
             items: {
                 type: 'object',
                 properties: {
                     paperId: { type: 'string' },
                     screening: { type: 'string', enum: [...SCREENINGS] },
                     groupId: { type: ['string', 'null'] },
-                    shortlistOrder: { type: ['integer', 'null'] },
-                    note: { type: 'string' },
-                    tags: { type: 'array', items: { type: 'string' } },
                 },
                 required: ['paperId'],
                 additionalProperties: false,
@@ -247,7 +245,7 @@ export function literatureTools(service) {
         {
             name: 'literature_search',
             description: '检索免费开放学术文献。并发查询 PubMed、Europe PMC、OpenAlex、Crossref、Semantic Scholar、arXiv、PubTator，跨源与跨检索式去重合并成一篇文献一条，返回标题、作者、年份、出处、DOI、被引次数、开放获取状态与摘要，支持一次提交多条检索式（queries）。' +
-                '【任务模型】一个研究主题 = 一个任务 = 一个右侧栏 tab；一个对话只保留一个任务 tab，切换任务由用户在任务列表里完成。若不确定这个对话当前用哪个任务，先调用 literature_task（action=current）查清再执行。默认复用「当前任务」并在同一任务内开新一轮：任务 id 不变、tab 不变，结果替换为最新一轮，已有的已读/纳入/排除/备注按文献身份保留；绝不会新建任务或新开 tab。当前任务是持久化的「最近一次使用或打开的任务」，跨对话、宿主重启都有效；用户从右侧栏点开别的任务会切换当前任务。只有用户明确要求新建查询任务，或研究主题与当前任务明显不同时，才传 newTask=true 并用 title 给新任务起一个概括主题的名称；也可用 taskId 显式指定要复用的任务（先用 literature_task current/list 查 id，或让用户点右侧栏的「带入对话」把任务 id 带进对话）。每次调用请提交【完整】的新检索条件，缺省项回落到插件默认设置而非沿用旧条件。' +
+                '【任务模型】一个研究主题 = 一个任务 = 一个右侧栏 tab；一个对话只保留一个任务 tab，切换任务由用户在任务列表里完成。若不确定这个对话当前用哪个任务，先调用 literature_task（action=current）查清再执行。默认复用「当前任务」并在同一任务内开新一轮：任务 id 不变、tab 不变，结果替换为最新一轮，已有的已读/纳入/排除/备注按文献身份保留；绝不会新建任务或新开 tab。当前任务是持久化的「最近一次使用或打开的任务」，跨对话、宿主重启都有效；用户从右侧栏点开别的任务会切换当前任务。只有用户明确要求新建查询任务，或研究主题与当前任务明显不同时，才传 newTask=true 并用 title 给新任务起一个概括主题的名称；也可用 taskId 显式指定要复用的任务（先用 literature_task current/list 查 id，或让用户点右侧栏的「加入对话」把任务 id 带进对话）。每次调用请提交【完整】的新检索条件，缺省项回落到插件默认设置而非沿用旧条件。' +
                 '【轮次约束】本轮检索结束后，只给用户一份「如何完善检索」的建议，禁止自行发起下一轮、禁止重复调用本工具；必须等用户查看结果后，在右侧栏调整条件、或在对话里明确要求调整，才可在同一任务里再搜一次。' +
                 '超过 25 秒仍在进行时会先返回当前进度，任务会继续在右侧栏完成。适合找论文、查某主题的代表作、补充参考文献。',
             parameters: SEARCH_PARAMETERS,
@@ -255,7 +253,13 @@ export function literatureTools(service) {
             async execute(args, exec) {
                 const input = readSearchArgs(args);
                 const { title, taskId, newTask, ...conditions } = input;
-                const createInput = { ...conditions, origin: 'model', runNow: false };
+                const workspace = await resolveSessionWorkspace(exec.agent?.id);
+                const createInput = {
+                    ...conditions,
+                    origin: 'model',
+                    runNow: false,
+                    ...(workspace === undefined ? {} : { workspace }),
+                };
                 let task;
                 let reused = false;
                 if (taskId !== undefined) {
@@ -315,7 +319,7 @@ export function literatureTools(service) {
         },
         {
             name: 'literature_sources',
-            description: '列出本插件已接入的免费文献数据源：能力（摘要、被引次数、开放获取、PDF 链接）、限流额度、检索式语法与是否需要可选 API Key。',
+            description: '列出本插件已接入的文献数据源：能力（摘要、被引次数、开放获取、PDF 链接）、限流额度、检索式语法与是否需要可选 API Key。默认数据源均免费；Google Scholar 需在设置页配置 SerpAPI Key（有免费额度，超出付费），未配置时不参与检索。',
             parameters: { type: 'object', properties: {}, additionalProperties: false },
             output: TEXT_OUTPUT,
             async execute() {
@@ -324,7 +328,7 @@ export function literatureTools(service) {
         },
         {
             name: 'literature_task',
-            description: '读取与推进已保存的检索任务。current 读「当前任务」（推荐在执行任何检索/任务操作前先调用，确认这个对话正在用哪个任务；无需 id）；list 列出任务；get 读条件、分组、笔记与结果（可按筛读/分组/检索式/关键词过滤）；update 改标题、条件、任务笔记与分组；rounds 读该任务的检索轮次历史（每轮时间、条件、发起方、命中数与状态）；annotate 批量写入筛读状态、分组、必读顺序、备注与标签；compare 与旧任务按论文身份对比新增/缺失；stats 读语料统计（年份、来源、期刊、作者、类型、语言）。' +
+            description: '读取与推进已保存的检索任务。current 读「当前任务」（推荐在执行任何检索/任务操作前先调用，确认这个对话正在用哪个任务；无需 id）；list 列出任务；get 读条件、分组、笔记与结果（可按筛读/分组/检索式/关键词过滤）；update 改标题、条件、任务笔记与分组；rounds 读该任务的检索轮次历史（每轮时间、条件、发起方、命中数与状态）；annotate 批量写入筛读状态与分组；compare 与旧任务按论文身份对比新增/缺失；stats 读语料统计（年份、来源、期刊、作者、类型、语言）。' +
                 '注意：一个对话只保留一个任务 tab，切换任务由用户在任务列表里完成；run 会在指定任务内开新一轮检索（并把它设为当前任务），与 literature_search 一样受「用户查看结果并明确要求后才能进入下一轮」约束，不能用它绕过该约束自行加搜；也不要用 update 改完条件就立刻 run。适合在检索之后做筛选、整理与汇报。',
             parameters: TASK_PARAMETERS,
             output: TEXT_OUTPUT,
@@ -336,7 +340,7 @@ export function literatureTools(service) {
         },
         {
             name: 'literature_export',
-            description: '把检索任务导出为文件并返回落盘路径。csv 是全量筛读台账（含命中检索式、筛读状态、分组、备注）；ris / bibtex 供 Zotero、EndNote 等文献管理器；md 是分层检索报告（漏斗、按分组的「为什么读」、必读清单、开放获取与 PDF 覆盖率、对比新增）。可按筛读状态、分组、检索式或指定 paperIds 限定范围。',
+            description: '把检索任务导出为文件并返回落盘路径。csv 是全量筛读台账（含命中检索式、筛读状态、分组）；ris / bibtex 供 Zotero、EndNote 等文献管理器；md 是分层检索报告（漏斗、按分组的阅读清单、开放获取与 PDF 覆盖率、对比新增）。可按筛读状态、分组、检索式或指定 paperIds 限定范围。',
             parameters: EXPORT_PARAMETERS,
             output: TEXT_OUTPUT,
             async execute(args) {
@@ -687,23 +691,6 @@ function readAnnotations(value) {
             }
             input.groupId = groupId;
         }
-        if (record['shortlistOrder'] !== undefined) {
-            const order = record['shortlistOrder'];
-            if (order !== null && (typeof order !== 'number' || !Number.isFinite(order))) {
-                throw new Error(`papers[${index}].shortlistOrder 必须是数字或 null`);
-            }
-            input.shortlistOrder = order;
-        }
-        const note = readText(record['note'], `papers[${index}].note`, true);
-        if (note !== undefined)
-            input.note = note;
-        if (record['tags'] !== undefined) {
-            const tags = record['tags'];
-            if (!Array.isArray(tags) || !tags.every((tag) => typeof tag === 'string')) {
-                throw new Error(`papers[${index}].tags 必须是字符串数组`);
-            }
-            input.tags = tags;
-        }
         return input;
     });
 }
@@ -769,10 +756,11 @@ async function runTaskAction(service, args, signal, sessionId) {
         case 'run': {
             const id = requireId(args);
             const task = await service.get(id);
+            const workspace = await resolveSessionWorkspace(sessionId);
             // 用户明确要求推进这个任务：它成为当前任务，并让客户端打开/聚焦对应 tab。
             service.setCurrentTask(id);
             service.focusTask(task.id, task.title, sessionId);
-            const outcome = await runWithin(service, id, signal, service.run(id, 'new', 'model'));
+            const outcome = await runWithin(service, id, signal, service.run(id, 'new', 'model', workspace));
             const latest = await service.get(id);
             const detail = await service.getDetail(id);
             const page = await service.results(id, {
@@ -790,7 +778,7 @@ async function runTaskAction(service, args, signal, sessionId) {
         }
         case 'annotate': {
             const result = await service.annotate(requireId(args), args.papers ?? []);
-            return `已写入 ${result.updated} 篇的筛读/备注（任务 id: ${result.taskId}，rev=${result.rev}）。`;
+            return `已写入 ${result.updated} 篇的筛读/分组（任务 id: ${result.taskId}，rev=${result.rev}）。`;
         }
         case 'compare': {
             const report = await service.compare(requireId(args), args.withTaskId ?? '');
@@ -853,7 +841,7 @@ function formatCurrentTask(task) {
     if (task === undefined) {
         return [
             '当前没有任务：这个对话还没有任何检索任务。',
-            '若用户要求检索，请直接调用 literature_search（不要传 newTask）；若用户要继续某个已有任务，请让用户从右侧栏任务列表打开它，或点任务页的「带入对话」把任务 id 带进对话。',
+            '若用户要求检索，请直接调用 literature_search（不要传 newTask）；若用户要继续某个已有任务，请让用户从右侧栏任务列表打开它，或点任务页的「加入对话」把任务 id 带进对话。',
         ].join('\n');
     }
     const conditions = task.conditions;
@@ -918,7 +906,6 @@ function formatTaskDetail(detail, page, states, groups, outcome) {
         const marks = [
             state?.screening ?? 'unread',
             state?.groupId === undefined ? '' : groupNames.get(state.groupId) ?? state.groupId,
-            state?.shortlistOrder === undefined ? '' : `必读#${state.shortlistOrder}`,
         ].filter((part) => part !== '');
         const meta = [
             paper.authors.slice(0, 4).join(', '),
@@ -930,8 +917,6 @@ function formatTaskDetail(detail, page, states, groups, outcome) {
         lines.push(`${page.offset + index + 1}. [${marks.join('|')}] ${paper.title}`);
         if (meta.length > 0)
             lines.push(`   ${meta.join(' | ')}`);
-        if (state?.note !== undefined && state.note !== '')
-            lines.push(`   备注：${state.note}`);
         if (paper.abstract !== '')
             lines.push(`   摘要：${truncate(paper.abstract, 300)}`);
     });
@@ -1002,7 +987,9 @@ function percent(value) {
     return `${Math.round(value * 100)}%`;
 }
 function formatSources() {
-    const lines = ['已接入的免费文献数据源（无需付费；部分支持可选 Key 提高额度）：'];
+    const lines = [
+        '已接入的文献数据源（默认均为免费；Google Scholar 需在设置页配置 SerpAPI Key，未配置时不参与检索）：',
+    ];
     for (const info of PROVIDER_INFOS) {
         const caps = [
             info.capabilities.abstract ? '摘要' : '',

package/lib/host/workspace.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 会话工作目录解析。
+ *
+ * DSH 为每个会话保存一个绝对工作目录（SessionHeader.cwd）。PDF 默认落在
+ * 该目录下的 `dsh-litsearch/`，让下载物跟随项目而不是散落到 `~/Downloads`。
+ * 会话服务由宿主注入；未装配或读不到时返回 undefined，由调用方回落到旧默认。
+ */
+/** `ctx.sessionPersistence` 中本插件用到的最小结构。 */
+export interface SessionStoreLike {
+    stat(id: string): Promise<{
+        header: {
+            cwd?: string;
+        };
+    } | undefined>;
+}
+export declare function setSessionStore(store: SessionStoreLike | undefined): void;
+/** 读取某个会话的工作目录；只接受绝对路径。 */
+export declare function resolveSessionWorkspace(sessionId: string | undefined): Promise<string | undefined>;
+/** 规范化工作目录：去空白、去尾斜杠，只接受绝对路径。 */
+export declare function normalizeWorkspace(value: string | undefined): string | undefined;

package/lib/host/workspace.js

@@ -0,0 +1,32 @@
+/**
+ * 会话工作目录解析。
+ *
+ * DSH 为每个会话保存一个绝对工作目录（SessionHeader.cwd）。PDF 默认落在
+ * 该目录下的 `dsh-litsearch/`，让下载物跟随项目而不是散落到 `~/Downloads`。
+ * 会话服务由宿主注入；未装配或读不到时返回 undefined，由调用方回落到旧默认。
+ */
+import { isAbsolute, resolve } from 'node:path';
+let sessionStore;
+export function setSessionStore(store) {
+    sessionStore = store;
+}
+/** 读取某个会话的工作目录；只接受绝对路径。 */
+export async function resolveSessionWorkspace(sessionId) {
+    const id = sessionId?.trim() ?? '';
+    if (id === '' || sessionStore === undefined)
+        return undefined;
+    try {
+        const snapshot = await sessionStore.stat(id);
+        return normalizeWorkspace(snapshot?.header.cwd);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 规范化工作目录：去空白、去尾斜杠，只接受绝对路径。 */
+export function normalizeWorkspace(value) {
+    const path = value?.trim() ?? '';
+    if (path === '' || !isAbsolute(path))
+        return undefined;
+    return resolve(path);
+}

package/lib/index.d.ts

@@ -14,6 +14,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
+import type { TaskLanguage } from './search/types.js';
 export declare const name = "dsh-plugin-litsearch";
 /**
  * 插件配置 schema（逐字段 volatile）。
@@ -28,6 +29,8 @@ export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
     ncbiApiKey: Schema<string, string, "volatile-defined">;
     /** 可选 Semantic Scholar API Key。 */
     s2ApiKey: Schema<string, string, "volatile-defined">;
+    /** 可选 SerpAPI Key；配置后启用 Google Scholar 数据源（付费/有免费额度）。 */
+    serpApiKey: Schema<string, string, "volatile-defined">;
     /** 各源最小请求间隔（毫秒）。 */
     pubmedIntervalMs: Schema<number, number, "volatile-defined">;
     s2IntervalMs: Schema<number, number, "volatile-defined">;
@@ -37,22 +40,24 @@ export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
     /** 单次上游请求超时（毫秒）。 */
     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">;
+    defaultSources: Schema<NoInfer<("pubmed" | "europepmc" | "openalex" | "crossref" | "semanticscholar" | "arxiv" | "pubtator" | "googlescholar")[]>, NoInfer<("pubmed" | "europepmc" | "openalex" | "crossref" | "semanticscholar" | "arxiv" | "pubtator" | "googlescholar")[]>, "volatile-defined">;
     defaultSort: Schema<"relevance" | "citations" | "year", "relevance" | "citations" | "year", "volatile-defined">;
-    defaultLanguage: Schema<"any" | "eng" | "chi", "any" | "eng" | "chi", "volatile-defined">;
+    defaultLanguage: Schema<TaskLanguage, TaskLanguage, "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 下载根目录。 */
+    /** PDF 下载根目录；留空时跟随会话工作目录（其下的 dsh-litsearch/）。 */
     pdfRoot: Schema<string, string, "volatile-defined">;
     /** 单个 PDF 最大体积（MB）。 */
     pdfMaxMb: Schema<number, number, "volatile-defined">;
+    /** PDF 去重缓存总量上限（MB），启动时随任务清理一起修剪；0 表示关闭。 */
+    pdfCacheMaxMb: Schema<number, number, "volatile-defined">;
     /** 检索完成后自动下载缺失 PDF。 */
     autoDownloadPdf: Schema<boolean, boolean, "volatile-defined">;
     /** 无 PDF 时用 Europe PMC HTML 全文兜底。 */
@@ -69,6 +74,8 @@ export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
     ncbiApiKey: Schema<string, string, "volatile-defined">;
     /** 可选 Semantic Scholar API Key。 */
     s2ApiKey: Schema<string, string, "volatile-defined">;
+    /** 可选 SerpAPI Key；配置后启用 Google Scholar 数据源（付费/有免费额度）。 */
+    serpApiKey: Schema<string, string, "volatile-defined">;
     /** 各源最小请求间隔（毫秒）。 */
     pubmedIntervalMs: Schema<number, number, "volatile-defined">;
     s2IntervalMs: Schema<number, number, "volatile-defined">;
@@ -78,22 +85,24 @@ export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
     /** 单次上游请求超时（毫秒）。 */
     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">;
+    defaultSources: Schema<NoInfer<("pubmed" | "europepmc" | "openalex" | "crossref" | "semanticscholar" | "arxiv" | "pubtator" | "googlescholar")[]>, NoInfer<("pubmed" | "europepmc" | "openalex" | "crossref" | "semanticscholar" | "arxiv" | "pubtator" | "googlescholar")[]>, "volatile-defined">;
     defaultSort: Schema<"relevance" | "citations" | "year", "relevance" | "citations" | "year", "volatile-defined">;
-    defaultLanguage: Schema<"any" | "eng" | "chi", "any" | "eng" | "chi", "volatile-defined">;
+    defaultLanguage: Schema<TaskLanguage, TaskLanguage, "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 下载根目录。 */
+    /** PDF 下载根目录；留空时跟随会话工作目录（其下的 dsh-litsearch/）。 */
     pdfRoot: Schema<string, string, "volatile-defined">;
     /** 单个 PDF 最大体积（MB）。 */
     pdfMaxMb: Schema<number, number, "volatile-defined">;
+    /** PDF 去重缓存总量上限（MB），启动时随任务清理一起修剪；0 表示关闭。 */
+    pdfCacheMaxMb: Schema<number, number, "volatile-defined">;
     /** 检索完成后自动下载缺失 PDF。 */
     autoDownloadPdf: Schema<boolean, boolean, "volatile-defined">;
     /** 无 PDF 时用 Europe PMC HTML 全文兜底。 */

package/lib/index.js

@@ -18,9 +18,12 @@ 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';
+import { setSessionStore } from './host/workspace.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_CACHE_MAX_MB, DEFAULT_PDF_MAX_MB, DEFAULT_PUBMED_INTERVAL_MS, DEFAULT_RETENTION_COUNT, DEFAULT_RETENTION_DAYS, DEFAULT_S2_INTERVAL_MS, DEFAULT_SOURCE_IDS, 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, TASK_LANGUAGES } from './search/types.js';
 export const name = 'dsh-plugin-litsearch';
+/** 旧版默认下载目录；读取时视为「未配置」，让默认落点切换到工作目录。 */
+const LEGACY_PDF_ROOT = join(homedir(), 'Downloads', 'dsh-litsearch');
 /**
  * 插件配置 schema（逐字段 volatile）。
  *
@@ -34,6 +37,8 @@ export const Config = Schema.object({
     ncbiApiKey: Schema.string().default('').role('secret').volatile(),
     /** 可选 Semantic Scholar API Key。 */
     s2ApiKey: Schema.string().default('').role('secret').volatile(),
+    /** 可选 SerpAPI Key；配置后启用 Google Scholar 数据源（付费/有免费额度）。 */
+    serpApiKey: Schema.string().default('').role('secret').volatile(),
     /** 各源最小请求间隔（毫秒）。 */
     pubmedIntervalMs: Schema.number().default(DEFAULT_PUBMED_INTERVAL_MS).volatile(),
     s2IntervalMs: Schema.number().default(DEFAULT_S2_INTERVAL_MS).volatile(),
@@ -51,8 +56,9 @@ export const Config = Schema.object({
         Schema.const('semanticscholar'),
         Schema.const('arxiv'),
         Schema.const('pubtator'),
+        Schema.const('googlescholar'),
     ]))
-        .default([...SOURCE_IDS])
+        .default([...DEFAULT_SOURCE_IDS])
         .volatile(),
     defaultSort: Schema.union([
         Schema.const('relevance'),
@@ -61,22 +67,24 @@ export const Config = Schema.object({
     ])
         .default(DEFAULT_SORT)
         .volatile(),
-    defaultLanguage: Schema.union([Schema.const('any'), Schema.const('eng'), Schema.const('chi')])
+    defaultLanguage: Schema.union(TASK_LANGUAGES.map((code) => Schema.const(code)))
         .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 下载根目录；留空时跟随会话工作目录（其下的 dsh-litsearch/）。 */
+    pdfRoot: Schema.string().default('').volatile(),
     /** 单个 PDF 最大体积（MB）。 */
     pdfMaxMb: Schema.number().default(DEFAULT_PDF_MAX_MB).volatile(),
+    /** PDF 去重缓存总量上限（MB），启动时随任务清理一起修剪；0 表示关闭。 */
+    pdfCacheMaxMb: Schema.number().default(DEFAULT_PDF_CACHE_MAX_MB).volatile(),
     /** 检索完成后自动下载缺失 PDF。 */
     autoDownloadPdf: Schema.boolean().default(DEFAULT_AUTO_DOWNLOAD_PDF).volatile(),
     /** 无 PDF 时用 Europe PMC HTML 全文兜底。 */
@@ -93,12 +101,13 @@ export function apply(ctx, config) {
         contactEmail: config.contactEmail.get().trim(),
         ncbiApiKey: config.ncbiApiKey.get().trim(),
         s2ApiKey: config.s2ApiKey.get().trim(),
+        serpApiKey: config.serpApiKey.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()),
+        defaultSources: normalizeSources(config.defaultSources.get()).filter((id) => id !== 'googlescholar' || config.serpApiKey.get().trim() !== ''),
         defaultSort: normalizeSort(config.defaultSort.get()),
         defaultLanguage: normalizeLanguage(config.defaultLanguage.get()),
         autoOpenTaskTab: config.autoOpenTaskTab.get(),
@@ -106,8 +115,9 @@ export function apply(ctx, config) {
         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(),
+        pdfRoot: normalizePdfRoot(config.pdfRoot.get()),
         pdfMaxMb: clampInt(config.pdfMaxMb.get(), 1, 200, DEFAULT_PDF_MAX_MB),
+        pdfCacheMaxMb: clampInt(config.pdfCacheMaxMb.get(), 0, 102_400, DEFAULT_PDF_CACHE_MAX_MB),
         autoDownloadPdf: config.autoDownloadPdf.get(),
         enableEpmcFulltext: config.enableEpmcFulltext.get(),
         zoteroEnabled: config.zoteroEnabled.get(),
@@ -118,6 +128,13 @@ export function apply(ctx, config) {
     // 任务状态是模型工具与 HTTP 路由的唯一事实源。
     const service = new TaskService();
     ctx.effect(() => () => service.dispose(), 'dsh-plugin-litsearch: task service');
+    // 会话工作目录：PDF 默认落在其中，跟随用户当前项目。
+    ctx.inject(['sessionPersistence'], (sessionCtx) => {
+        const store = sessionCtx
+            .sessionPersistence;
+        setSessionStore(store);
+        sessionCtx.effect(() => () => setSessionStore(undefined), 'dsh-plugin-litsearch: session workspace');
+    });
     // 模型侧：原生注册，不依赖外部 MCP。
     ctx.inject(['tools'], (toolCtx) => {
         const toolsService = toolCtx.tools;
@@ -139,15 +156,20 @@ function clampInt(value, min, max, fallback) {
 }
 function normalizeSources(value) {
     const valid = SOURCE_IDS.filter((id) => value.includes(id));
-    return valid.length === 0 ? [...SOURCE_IDS] : valid;
+    return valid.length === 0 ? [...DEFAULT_SOURCE_IDS] : valid;
 }
 function normalizeSort(value) {
     return value === 'citations' || value === 'year' ? value : 'relevance';
 }
 function normalizeLanguage(value) {
-    return value === 'eng' || value === 'chi' ? value : 'any';
+    return TASK_LANGUAGES.includes(value) ? value : 'any';
 }
 function normalizeBaseUrl(value) {
     const trimmed = value.trim().replace(/\/+$/u, '');
     return /^https?:\/\//u.test(trimmed) ? trimmed : DEFAULT_ZOTERO_BASE_URL;
 }
+/** 旧默认值等同未配置：改由会话工作目录决定下载落点。 */
+function normalizePdfRoot(value) {
+    const trimmed = value.trim();
+    return trimmed === LEGACY_PDF_ROOT ? '' : trimmed;
+}

package/lib/search/aggregate.js

@@ -39,6 +39,7 @@ export async function searchSources(options) {
             bypassCooldown: options.bypassCooldown === true,
             ncbiApiKey: settings.ncbiApiKey,
             s2ApiKey: settings.s2ApiKey,
+            serpApiKey: settings.serpApiKey,
         });
     }));
     return settled.map((outcome, index) => {

package/lib/search/config.d.ts

@@ -7,6 +7,13 @@
 import type { SortMode, SourceId, TaskLanguage } from './types.js';
 /** 插件版本（与 package.json 同步；仅用于 /health 诊断展示）。 */
 export declare const PLUGIN_VERSION = "0.1.0";
+/**
+ * 默认数据源。
+ *
+ * Google Scholar 依赖用户自备的 SerpAPI Key，未配置时默认关闭，
+ * 因此不进入默认勾选列表。
+ */
+export declare const DEFAULT_SOURCE_IDS: readonly SourceId[];
 /** 默认每次加载条数。 */
 export declare const DEFAULT_PAGE_SIZE = 20;
 /**
@@ -37,8 +44,12 @@ export declare const DEFAULT_TASK_MAX_ROUNDS = 30;
 export declare const DEFAULT_PUBMED_INTERVAL_MS = 350;
 export declare const DEFAULT_S2_INTERVAL_MS = 3000;
 export declare const DEFAULT_ARXIV_INTERVAL_MS = 3000;
+/** SerpAPI 按次计费，保守限制为 1 次/秒。 */
+export declare const DEFAULT_SERPAPI_INTERVAL_MS = 1000;
 /** 全文下载默认设置。 */
 export declare const DEFAULT_PDF_MAX_MB = 30;
+/** PDF 去重缓存总量上限（MB）；0 表示关闭自动清理。 */
+export declare const DEFAULT_PDF_CACHE_MAX_MB = 512;
 export declare const DEFAULT_AUTO_DOWNLOAD_PDF = false;
 export declare const DEFAULT_ENABLE_EPMC_FULLTEXT = true;
 /** Zotero connector 默认设置。 */
@@ -50,6 +61,8 @@ 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";
+/** 面板请求携带的会话 id；Host 用它解析会话工作目录。 */
+export declare const SESSION_HEADER = "x-dsh-litsearch-session";
 /** Host 路由前缀（Client fetch 路径与 handler 的剥离基准，带尾斜杠）。 */
 export declare const ROUTE_PREFIX = "/dsh-litsearch/api/";
 /**
@@ -76,13 +89,16 @@ export interface LitsearchSettings {
     ncbiApiKey: string;
     /** 可选 Semantic Scholar API Key；提高配额。 */
     s2ApiKey: string;
+    /** 可选 SerpAPI Key；配置后启用 Google Scholar 数据源。 */
+    serpApiKey: string;
     /** 各源最小请求间隔覆盖值。 */
     pubmedIntervalMs: number;
     s2IntervalMs: number;
     arxivIntervalMs: number;
-    /** PDF 下载根目录；空串由 Host 回落到 ~/Downloads/dsh-litsearch。 */
+    /** PDF 下载根目录；空串由 Host 回落到会话工作目录下的 dsh-litsearch/。 */
     pdfRoot: string;
     pdfMaxMb: number;
+    pdfCacheMaxMb: number;
     autoDownloadPdf: boolean;
     enableEpmcFulltext: boolean;
     zoteroEnabled: boolean;

package/lib/search/config.js

@@ -7,6 +7,13 @@
 import { SOURCE_IDS } from './types.js';
 /** 插件版本（与 package.json 同步；仅用于 /health 诊断展示）。 */
 export const PLUGIN_VERSION = '0.1.0';
+/**
+ * 默认数据源。
+ *
+ * Google Scholar 依赖用户自备的 SerpAPI Key，未配置时默认关闭，
+ * 因此不进入默认勾选列表。
+ */
+export const DEFAULT_SOURCE_IDS = SOURCE_IDS.filter((id) => id !== 'googlescholar');
 /** 默认每次加载条数。 */
 export const DEFAULT_PAGE_SIZE = 20;
 /**
@@ -37,8 +44,12 @@ export const DEFAULT_TASK_MAX_ROUNDS = 30;
 export const DEFAULT_PUBMED_INTERVAL_MS = 350;
 export const DEFAULT_S2_INTERVAL_MS = 3000;
 export const DEFAULT_ARXIV_INTERVAL_MS = 3000;
+/** SerpAPI 按次计费，保守限制为 1 次/秒。 */
+export const DEFAULT_SERPAPI_INTERVAL_MS = 1000;
 /** 全文下载默认设置。 */
 export const DEFAULT_PDF_MAX_MB = 30;
+/** PDF 去重缓存总量上限（MB）；0 表示关闭自动清理。 */
+export const DEFAULT_PDF_CACHE_MAX_MB = 512;
 export const DEFAULT_AUTO_DOWNLOAD_PDF = false;
 export const DEFAULT_ENABLE_EPMC_FULLTEXT = true;
 /** Zotero connector 默认设置。 */
@@ -50,6 +61,8 @@ export const DEFAULT_ZOTERO_TAG = 'dsh-litsearch';
 export const MAX_ABSTRACT_CHARS = 800;
 /** 写端点的自定义请求头（与 JSON content-type 一起构成非简单请求）。 */
 export const WRITE_HEADER = 'x-dsh-litsearch-write';
+/** 面板请求携带的会话 id；Host 用它解析会话工作目录。 */
+export const SESSION_HEADER = 'x-dsh-litsearch-session';
 /** Host 路由前缀（Client fetch 路径与 handler 的剥离基准，带尾斜杠）。 */
 export const ROUTE_PREFIX = '/dsh-litsearch/api/';
 /**
@@ -64,7 +77,7 @@ let readSettings = () => ({
     contactEmail: '',
     defaultPageSize: DEFAULT_PAGE_SIZE,
     requestTimeoutMs: REQUEST_TIMEOUT_MS,
-    defaultSources: [...SOURCE_IDS],
+    defaultSources: [...DEFAULT_SOURCE_IDS],
     defaultSort: DEFAULT_SORT,
     defaultLanguage: DEFAULT_LANGUAGE,
     autoOpenTaskTab: DEFAULT_AUTO_OPEN,
@@ -74,11 +87,13 @@ let readSettings = () => ({
     taskMaxPapers: DEFAULT_TASK_MAX_PAPERS,
     ncbiApiKey: '',
     s2ApiKey: '',
+    serpApiKey: '',
     pubmedIntervalMs: DEFAULT_PUBMED_INTERVAL_MS,
     s2IntervalMs: DEFAULT_S2_INTERVAL_MS,
     arxivIntervalMs: DEFAULT_ARXIV_INTERVAL_MS,
     pdfRoot: '',
     pdfMaxMb: DEFAULT_PDF_MAX_MB,
+    pdfCacheMaxMb: DEFAULT_PDF_CACHE_MAX_MB,
     autoDownloadPdf: DEFAULT_AUTO_DOWNLOAD_PDF,
     enableEpmcFulltext: DEFAULT_ENABLE_EPMC_FULLTEXT,
     zoteroEnabled: DEFAULT_ZOTERO_ENABLED,

package/lib/search/identity.js

@@ -17,6 +17,7 @@ const RRF_WEIGHTS = {
     semanticscholar: 0.9,
     arxiv: 0.85,
     pubtator: 0.7,
+    googlescholar: 0.95,
 };
 /** RRF 平滑常数。 */
 const RRF_K = 60;

package/lib/search/oa.d.ts

@@ -6,6 +6,14 @@
 import type { Paper } from './types.js';
 /** 去重后的 PDF 候选地址（顺序即尝试优先级）。 */
 export declare function pdfCandidates(paper: Paper): string[];
+/**
+ * 仓储的 PDF 渲染页：浏览器能打开，后台请求却普遍被拦截。
+ *
+ * 实测 `europepmc.org/articles/...?pdf=render` 返回 403 Cloudflare 页、
+ * `ncbi.nlm.nih.gov/pmc/articles/.../pdf/` 返回 200 但内容是 HTML 落地页。
+ * 它们仍保留为最后兜底，但必须排在所有静态直链与 Unpaywall 结果之后。
+ */
+export declare function isPdfRenderUrl(url: string): boolean;
 /** Europe PMC 的全文 XML 地址；没有 PMCID 时返回 null。 */
 export declare function epmcXmlUrl(paper: Paper): string | null;
 /** Unpaywall 查询（需要联系邮箱，遵守其 polite pool）。 */