dsh-plugin-litsearch 0.3.0 → 0.4.0

package/lib/search/types.d.ts

@@ -153,19 +153,33 @@ 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;
+/** 文献 → Zotero 的同步状态；缺省表示尚未同步。 */
+export type ZoteroSyncStatus = 'synced' | 'failed';
 /** 论文级人工筛选状态。 */
 export interface PaperState {
     screening: Screening;
     groupId?: string;
-    shortlistOrder?: number;
-    note?: string;
-    tags?: string[];
     pdfStatus?: PdfStatus;
     /** 失败原因（面向用户的一句话）。 */
     pdfError?: string;
     /** 已下载到用户目录的绝对路径。 */
     pdfFile?: string;
+    /** 最近一次 Zotero 同步结果；缺省为未同步。 */
+    zoteroStatus?: ZoteroSyncStatus;
+    /** 同步到的 Zotero 目录名，便于列表直接展示。 */
+    zoteroCollection?: string;
+    /** 同步失败原因（面向用户的一句话）。 */
+    zoteroError?: string;
 }
 export interface TaskGroup {
     id: string;
@@ -194,7 +208,7 @@ export interface TaskResult {
  * 任务内一次检索（一轮）的元数据快照。
  *
  * 只留「这一轮用什么条件、什么时候跑、跑出多少、结果如何」，**不保存文献列表**：
- * 当前结果永远是最新一轮的 `result.papers`，人工标注按 paperId 跨轮保留。
+ * 当前结果永远是最新一轮的 `result.papers`，筛读状态按 paperId 跨轮保留。
  * 历史轮次用于时间轴回看与「回填条件重跑」。
  */
 export interface SearchRound {
@@ -281,6 +295,8 @@ export interface TaskDetail extends TaskSummary {
     states: Record<string, PaperState>;
     /** 建立任务时继承筛读状态的来源任务。 */
     fromTaskId?: string;
+    /** PDF 实际保存目录（供面板悬停提示）。 */
+    downloadDir?: string;
     result: {
         totalLoaded: number;
         sources: SourceStatus[];
@@ -377,6 +393,7 @@ export interface FullTextCoverage {
     unknown: number;
     available: number;
     downloaded: number;
+    missing: number;
     htmlOnly: number;
     paywalled: number;
     blocked: number;
@@ -388,10 +405,6 @@ export interface AnnotationInput {
     screening?: Screening;
     /** `null` 表示移出分组。 */
     groupId?: string | null;
-    /** `null` 表示清除必读顺序。 */
-    shortlistOrder?: number | null;
-    note?: string;
-    tags?: string[];
     /** 全文状态由 Host 下载/同步流程写入，面板也可显示与筛选。 */
     pdfStatus?: PdfStatus;
     pdfError?: string;
@@ -407,6 +420,8 @@ export interface PdfDownloadResult {
     path?: string;
     url?: string;
     error?: string;
+    /** 失败根因；成功时缺省。 */
+    reason?: PdfFailureReason;
 }
 /** Zotero connector 探测结果。 */
 export interface ZoteroProbeResult {
@@ -420,6 +435,32 @@ export interface ZoteroProbeResult {
     };
     error?: string;
 }
+/** Zotero 可写入的目标（库或分类），id 为 connector 的 treeViewID。 */
+export interface ZoteroTarget {
+    id: string;
+    name: string;
+    level: number;
+    filesEditable?: boolean;
+    recent?: boolean;
+}
+/** Zotero 目标目录列表。 */
+export interface ZoteroTargetsResult {
+    ok: boolean;
+    targets: ZoteroTarget[];
+    /** 当前 Zotero 里选中的目标。 */
+    current?: {
+        id: string;
+        name: string;
+    };
+    error?: string;
+}
+/** 单篇同步结果。 */
+export interface ZoteroSyncItemResult {
+    paperId: string;
+    ok: boolean;
+    attached: boolean;
+    error?: string;
+}
 /** Zotero 批量同步结果。 */
 export interface ZoteroSyncResult {
     ok: boolean;
@@ -427,6 +468,7 @@ export interface ZoteroSyncResult {
     attached: number;
     failed: number;
     messages: string[];
+    items: ZoteroSyncItemResult[];
 }
 /** 下载目录可写性测试结果。 */
 export interface StorageProbeResult {
@@ -448,6 +490,8 @@ export interface PaperDetail {
     paper: Paper;
     state?: PaperState;
     groups: TaskGroup[];
+    /** PDF 实际保存目录（供面板悬停提示）。 */
+    downloadDir?: string;
 }
 /** PubTator 标注的单个实体（按标识符与原文去重）。 */
 export interface PaperEntity {
@@ -532,12 +576,113 @@ export interface TaskFocus {
     /** 发起检索的会话；客户端只在该会话可见时打开，避免抢占其他对话的面板。 */
     sessionId?: string;
 }
+/**
+ * 结果列表每页篇数。
+ *
+ * 面板分页与模型侧「第 N 页」共用这一个常量：它是**界面翻页**的粒度，
+ * 与任务条件的 `pageSize`（每源条数，可调 1–50）不是一回事，两者不可混用。
+ */
+export declare const RESULT_PAGE_SIZE = 20;
+/** 模型侧下载范围；工具把自然语言收敛成这 7 种之一。 */
+export type DownloadScope = 'ids' | 'currentPage' | 'currentView' | 'pages' | 'all' | 'group' | 'filters';
+/**
+ * 按页取数时页码的基准列表。
+ *
+ * - `view`（默认）：先按面板视图（筛选 + 排序）切页，再在页内套模型附加条件。
+ *   「第二页里有 PDF 的文献」就是这个口径：用户看到的是第 2 页那 20 条。
+ * - `filtered`：先把附加条件合并进筛选再切页。
+ *   「有 PDF 的文献的第 2 页」用这个。
+ */
+export type PageBase = 'view' | 'filtered';
+/**
+ * 客户端当前视图快照。
+ *
+ * 模型工具跑在 Host 侧，看不到右侧栏翻到第几页、用了什么筛选。面板按变化
+ * 节流上报这份快照，Host 才能把「当前页」「当前筛选全部」算准。仅存内存，
+ * 宿主重启即失效（与事件日志 rev 一致）。
+ */
+export interface ViewSnapshot {
+    sessionId: string;
+    taskId: string;
+    /** 上报时间（epoch ms）；Host 只接受 30 分钟内的快照。 */
+    at: number;
+    pageIndex: number;
+    pageSize: number;
+    /** 客户端看到的结果总数；给出「共 N 页」时用它，缺省则由 Host 按任务重算。 */
+    total?: number;
+    /** 当前结果排序；快照缺 paperIds 时用它重算当前页。 */
+    sort?: SortMode;
+    /** 当前生效的筛选；键名沿用 ResultsQuery，值已去除 undefined / 空串。 */
+    filters: Record<string, string | number | boolean>;
+    /** 当前页按用户所见顺序的 paperId。 */
+    pagePaperIds: string[];
+    /** 跨页累计勾选的 paperId。 */
+    selectedIds: string[];
+    /** 客户端看到的任务 rev；每下载一篇都会自增，故只做宽松校验。 */
+    rev: number;
+}
+/** 一条待下载文献的展示元数据；由 Host 生成，Client 无需再查详情。 */
+export interface DownloadCommandItem {
+    paperId: string;
+    title: string;
+    source: string;
+    /** `期刊 · 年份` 之类的副行，可缺省。 */
+    meta?: string;
+}
+/**
+ * 模型发起的批量下载指令。
+ *
+ * 范围在 Host 侧已解析、逐个校验完毕；右侧栏只按 paperIds 执行，不解析
+ * 任何条件，也不反查别的任务。弹窗靠 scopeLabel / reason / items 让用户
+ * 看清「大模型正在下载哪些文献」。
+ */
+export interface DownloadCommand {
+    commandId: string;
+    taskId: string;
+    sessionId?: string;
+    at: number;
+    origin: 'model';
+    /** 用户原话 / 模型对范围的解释，弹窗里展示。 */
+    reason: string;
+    /** Host 生成的中文范围说明（含篇数），Client 纯展示。 */
+    scopeLabel: string;
+    paperIds: string[];
+    items: DownloadCommandItem[];
+}
+/**
+ * 模型发起的批量存入 Zotero 指令。
+ *
+ * 与下载指令共用同一套范围解析与 `items` 展示元数据；多出来的只有目标目录：
+ * 用户在对话里点名了目录且 Host 匹配成功时带上 `target` 并 `autoStart`，
+ * 否则弹窗加载好文献后由用户自己选目录再点「同步」。
+ */
+export interface ZoteroCommand {
+    commandId: string;
+    taskId: string;
+    sessionId?: string;
+    at: number;
+    origin: 'model';
+    /** 用户原话 / 模型对范围的解释，弹窗里展示。 */
+    reason: string;
+    /** Host 生成的中文范围说明（含篇数），Client 纯展示。 */
+    scopeLabel: string;
+    paperIds: string[];
+    items: DownloadCommandItem[];
+    /** 对话里点名、且已在 Zotero 目录列表里核实过的目标目录。 */
+    target?: ZoteroTarget;
+    /** true = 目录已确定，弹窗加载完立即自动同步；false = 等用户选目录。 */
+    autoStart: boolean;
+}
 /** `/events` 的响应；`reset` 表示客户端的 sinceRev 比服务端新（宿主重启）。 */
 export interface EventsPage {
     rev: number;
     reset: boolean;
     tasks: TaskSummary[];
     focus?: TaskFocus;
+    /** 增量下发的模型下载指令；数组而非单值，避免两次轮询间连发时丢指令。 */
+    downloads?: DownloadCommand[];
+    /** 增量下发的模型 Zotero 同步指令，与 downloads 并列、互不影响。 */
+    zotero?: ZoteroCommand[];
 }
 /** `/health` 的响应：数据源能力 + 客户端需要的默认设置（不含密钥）。 */
 export interface HealthInfo {
@@ -573,7 +718,6 @@ export interface HealthInfo {
     };
     /** 任务文件存放目录（设置页只读展示）。 */
     storageDir: string;
-    version: string;
 }
 /** Host HTTP 端点统一信封。 */
 export type ApiEnvelope<T> = {

package/lib/search/types.js

@@ -33,3 +33,14 @@ export const TASK_LANGUAGES = [
     'ita',
     'por',
 ];
+/** 是否需要引导用户到浏览器手动保存。 */
+export function isManualPdfFailure(reason) {
+    return reason !== undefined && reason !== 'failed';
+}
+/**
+ * 结果列表每页篇数。
+ *
+ * 面板分页与模型侧「第 N 页」共用这一个常量：它是**界面翻页**的粒度，
+ * 与任务条件的 `pageSize`（每源条数，可调 1–50）不是一回事，两者不可混用。
+ */
+export const RESULT_PAGE_SIZE = 20;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-litsearch",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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",