dsh-plugin-litsearch 0.0.0-stage → 0.2.0

package/lib/host/tasks/service.d.ts

@@ -0,0 +1,171 @@
+/**
+ * TaskService：任务工作台的唯一事实源。
+ *
+ * 负责校验/规范化任务条件、维护内存与磁盘状态、串行化执行并广播 rev。
+ * 模型工具与面板 HTTP 路由都只调用这里，保证两边操作同一份状态。
+ */
+import type { AnnotationInput, AnnotationResult, CleanupResult, CleanupScope, CompareResult, EventsPage, ExportFile, ExportFormat, HealthInfo, PaperDetail, PaperEntities, PdfDownloadResult, ProbeResult, QueryBlock, ResultsPage, SearchRound, SearchTask, SortMode, SourceId, StorageProbeResult, TaskDetail, TaskGroup, TaskLanguage, TaskOrigin, TaskStatsReport, TaskSummary, ZoteroProbeResult, ZoteroSyncResult } from '../../search/types.js';
+import { type PaperFilter } from './filter.js';
+export interface QueryInput {
+    name?: string;
+    text: string;
+    perSource?: QueryBlock['perSource'];
+    enabled?: boolean;
+}
+export interface CreateTaskInput {
+    title?: string;
+    query?: string;
+    queries?: QueryInput[];
+    sources?: SourceId[];
+    pageSize?: number;
+    yearFrom?: number;
+    yearTo?: number;
+    openAccessOnly?: boolean;
+    language?: TaskLanguage;
+    types?: string[];
+    sort?: SortMode;
+    origin: TaskOrigin;
+    fromTaskId?: string;
+    runNow?: boolean;
+}
+export interface TaskPatch {
+    title?: string;
+    notes?: string;
+    pinned?: boolean;
+    groups?: TaskGroup[];
+    conditions?: {
+        queries?: QueryInput[];
+        sources?: SourceId[];
+        pageSize?: number;
+        yearFrom?: number | null;
+        yearTo?: number | null;
+        openAccessOnly?: boolean;
+        language?: TaskLanguage;
+        types?: string[] | null;
+        sort?: SortMode;
+    };
+}
+export interface ResultsFilter extends PaperFilter {
+    offset?: number;
+    limit?: number;
+    sort?: SortMode;
+}
+export interface TaskListFilter {
+    q?: string;
+    origin?: TaskOrigin;
+    pinned?: boolean;
+}
+export declare class TaskService {
+    readonly ready: Promise<void>;
+    private readonly store;
+    private readonly events;
+    private readonly runner;
+    /**
+     * 全局「当前任务」：最后一次使用或打开的任务。
+     *
+     * 不按对话、也不按时间过期——同一主题的后续检索必须在原任务里加一轮，
+     * 跨对话、宿主重启都成立。只有用户显式新建任务或点开别的任务时才会改变。
+     */
+    private currentTaskId;
+    private currentTaskAt;
+    constructor();
+    /**
+     * 先加载任务索引，再恢复「当前任务」快照。
+     *
+     * 快照缺失或指向已删除任务时，自举为最近更新的任务，避免下一轮检索
+     * 又新建一个同名任务。
+     */
+    private restore;
+    /** 没有可用快照时，把最近更新的任务设为当前任务并落盘。 */
+    private bootstrapCurrentTask;
+    get globalRev(): number;
+    get root(): string;
+    isRunning(id: string): boolean;
+    health(): HealthInfo;
+    eventsSince(sinceRev: number): Promise<EventsPage>;
+    list(filter?: TaskListFilter): Promise<TaskSummary[]>;
+    get(id: string): Promise<SearchTask>;
+    getDetail(id: string): Promise<TaskDetail>;
+    /** 任务内轮次历史（时间升序、深拷贝）。 */
+    getRounds(id: string): Promise<SearchRound[]>;
+    /**
+     * 当前任务：最近一次使用或打开的任务。
+     *
+     * 没有时间窗口、也不区分对话；只要任务还在就一直有效。任务被全部删除后
+     * 返回 undefined，由调用方决定是否新建。
+     */
+    currentTask(): Promise<SearchTask | undefined>;
+    /** 记住最近使用的任务（下一次模型检索默认落在这里）。 */
+    setCurrentTask(id: string): void;
+    /** 请求客户端打开/聚焦某任务 tab（面板被关掉时重新打开）。 */
+    focusTask(id: string, title: string, sessionId?: string): void;
+    private persistCurrent;
+    /** 用户从任务列表点开某任务 = 进入该任务，之后的模型检索默认落在这里。 */
+    activate(id: string): Promise<SearchTask>;
+    /** 等待该任务当前这一轮结束；返回是否确实已空闲。 */
+    waitUntilIdle(id: string, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
+    create(input: CreateTaskInput): Promise<SearchTask>;
+    update(id: string, patch: TaskPatch, expectedRev?: number): Promise<SearchTask>;
+    remove(id: string): Promise<void>;
+    /**
+     * 启动一次执行（任务内新一轮）；返回的 Promise 在运行结束后 resolve 为最新任务。
+     *
+     * 任务已缓存时同步登记运行态，调用方紧接着调 `waitUntilIdle` 也不会误判为空闲。
+     */
+    run(id: string, mode?: 'new' | 'more', origin?: TaskOrigin): Promise<SearchTask>;
+    /**
+     * 在同一任务内开新一轮：全量替换检索条件后执行，**不新建任务、不新开 tab**。
+     *
+     * 与 `update` 的增量 patch 不同，这里按 CreateTaskInput 重算条件，缺省项回落到
+     * 当前设置而不是沿用旧值，保证「提交完整新条件」的语义明确。
+     */
+    rerun(id: string, input: CreateTaskInput, origin: TaskOrigin): Promise<SearchTask>;
+    cancel(id: string): Promise<SearchTask>;
+    results(id: string, filter?: ResultsFilter): Promise<ResultsPage>;
+    stats(id: string, filter?: PaperFilter, scope?: 'task' | 'filtered'): Promise<TaskStatsReport>;
+    /** 写入筛读 / 分组 / 必读 / 备注；返回新的 rev 与命中条数。 */
+    annotate(id: string, inputs: readonly AnnotationInput[], expectedRev?: number): Promise<AnnotationResult>;
+    compare(id: string, withTaskId: string): Promise<CompareResult>;
+    /** 生成导出内容；`paperIds` 为空表示按当前筛选导出全部。 */
+    export(id: string, format: ExportFormat, filter?: PaperFilter, paperIds?: readonly string[]): Promise<ExportFile>;
+    /** 把导出内容写到 `<storage>/out/<taskId>/`，供模型工具返回落盘路径。 */
+    exportToDisk(id: string, format: ExportFormat, filter?: PaperFilter, paperIds?: readonly string[]): Promise<{
+        path: string;
+        file: ExportFile;
+        count: number;
+    }>;
+    /** 设置页清理：任务文件与 PDF 缓存。 */
+    cleanup(scope: CleanupScope): Promise<CleanupResult>;
+    /** 下载单篇 PDF；失败时写入失败状态，若有 EPMC 全文则降级为 html-only。 */
+    downloadPdf(id: string, paperId: string): Promise<PdfDownloadResult>;
+    /** PDF 预览：优先用已落地文件；没有则临时抓取一次但不落盘。 */
+    previewPdf(id: string, paperId: string): Promise<{
+        buffer: Buffer;
+        filename: string;
+    }>;
+    /** Europe PMC 全文（JATS → 只含安全标签的 HTML）。 */
+    fullText(id: string, paperId: string): Promise<string>;
+    /** 单篇论文详情：独立论文页使用，含任务标题与分组。 */
+    paperDetail(id: string, paperId: string): Promise<PaperDetail>;
+    /** PubTator3 实体标注；无 PMID 时明确告知不可标注。 */
+    entities(id: string, paperId: string, signal?: AbortSignal): Promise<PaperEntities>;
+    /** 测试 Zotero connector 是否可达，并返回当前选中的分类。 */
+    zoteroProbe(): Promise<ZoteroProbeResult>;
+    /** 把选中论文同步到 Zotero（含本地 PDF 附件）。 */
+    zoteroSync(id: string, paperIds?: readonly string[]): Promise<ZoteroSyncResult>;
+    /** 下载目录可写性测试（设置页）。 */
+    storageProbe(): Promise<StorageProbeResult>;
+    private ensureLocalPdf;
+    private setPdfState;
+    /** 单源诊断：用固定短查询测一次连通性与延迟（不受冷却影响）。 */
+    probe(source: SourceId): Promise<ProbeResult>;
+    private tryGet;
+    private baseInfo;
+    /** `newOnly` 需要基准任务的论文集合；基准已删除时忽略该条件。 */
+    private withBaseFilter;
+    dispose(): void;
+    private begin;
+    /** 任务完成后按设置自动下载少量开放获取 PDF（上限 10 篇，避免长时间占用网络）。 */
+    private autoDownloadPdfs;
+    private readConditions;
+}