dsh-plugin-litsearch 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,28 @@
+/**
+ * 筛读台账：论文级状态（四态筛读 / 分组 / 必读顺序 / 备注 / 标签）与任务分组。
+ *
+ * 所有写入口（面板注解、模型 `literature_task annotate`、分组编辑）都先经过
+ * 这里的校验，确保状态结构稳定；`states` 以稳定的 `paperId` 为键，因此跨任务
+ * 继承与重跑都不会错位。
+ */
+import type { AnnotationInput, Paper, PaperState, PdfStatus, Screening, SearchTask, TaskGroup } from '../../search/types.js';
+export declare const SCREENINGS: readonly Screening[];
+export declare const PDF_STATUSES: readonly PdfStatus[];
+export declare function isScreening(value: unknown): value is Screening;
+export declare function isPdfStatus(value: unknown): value is PdfStatus;
+export declare function emptyState(): PaperState;
+/** 当前任务里每篇论文的有效状态（缺省为未读）。 */
+export declare function stateOf(task: SearchTask, paperId: string): PaperState;
+/** 按当前结果集统计四态数量；被删掉的结果不计入。 */
+export declare function countScreening(papers: readonly Paper[], states: Readonly<Record<string, PaperState>>): Record<Screening, number>;
+/** 校验并合并一批注解；返回更新后的 states 与命中条数。 */
+export declare function applyAnnotations(task: SearchTask, inputs: readonly AnnotationInput[]): {
+    states: Record<string, PaperState>;
+    updated: number;
+};
+/** 校验分组列表：id 唯一、名称非空、顺序重排为连续整数。 */
+export declare function normalizeGroups(values: readonly TaskGroup[] | undefined): TaskGroup[] | undefined;
+/** 分组若仍有论文引用，删除前提醒调用方（调用方决定是否允许）。 */
+export declare function groupUsage(task: SearchTask, groupId: string): number;
+/** 按必读顺序、年份、标题排序某组的论文。 */
+export declare function sortGroupPapers(task: SearchTask, papers: readonly Paper[]): Paper[];

package/lib/host/tasks/states.js

@@ -0,0 +1,223 @@
+/**
+ * 筛读台账：论文级状态（四态筛读 / 分组 / 必读顺序 / 备注 / 标签）与任务分组。
+ *
+ * 所有写入口（面板注解、模型 `literature_task annotate`、分组编辑）都先经过
+ * 这里的校验，确保状态结构稳定；`states` 以稳定的 `paperId` 为键，因此跨任务
+ * 继承与重跑都不会错位。
+ */
+import { SearchError } from '../../search/errors.js';
+const MAX_ANNOTATIONS = 50;
+const MAX_GROUPS = 50;
+const MAX_GROUP_NAME = 60;
+const MAX_GROUP_DESCRIPTION = 500;
+const MAX_NOTE = 4000;
+const MAX_TAGS = 20;
+const MAX_TAG = 40;
+const MAX_PDF_ERROR = 300;
+const MAX_PDF_FILE = 1024;
+const MAX_SHORTLIST_ORDER = 100_000;
+export const SCREENINGS = ['unread', 'read', 'included', 'excluded'];
+export const PDF_STATUSES = [
+    'unknown',
+    'available',
+    'downloaded',
+    'html-only',
+    'paywalled',
+    'blocked',
+    'failed',
+];
+export function isScreening(value) {
+    return typeof value === 'string' && SCREENINGS.includes(value);
+}
+export function isPdfStatus(value) {
+    return typeof value === 'string' && PDF_STATUSES.includes(value);
+}
+export function emptyState() {
+    return { screening: 'unread' };
+}
+/** 当前任务里每篇论文的有效状态（缺省为未读）。 */
+export function stateOf(task, paperId) {
+    return task.states[paperId] ?? emptyState();
+}
+/** 按当前结果集统计四态数量；被删掉的结果不计入。 */
+export function countScreening(papers, states) {
+    const counts = { unread: 0, read: 0, included: 0, excluded: 0 };
+    for (const paper of papers) {
+        counts[states[paper.paperId]?.screening ?? 'unread'] += 1;
+    }
+    return counts;
+}
+/** 校验并合并一批注解；返回更新后的 states 与命中条数。 */
+export function applyAnnotations(task, inputs) {
+    if (inputs.length === 0)
+        throw new SearchError('bad_request', 'papers 不能为空');
+    if (inputs.length > MAX_ANNOTATIONS) {
+        throw new SearchError('bad_request', `一次最多注解 ${MAX_ANNOTATIONS} 篇`);
+    }
+    const known = new Set(task.result.papers.map((paper) => paper.paperId));
+    const groupIds = new Set(task.groups.map((group) => group.id));
+    const states = { ...task.states };
+    let updated = 0;
+    for (const input of inputs) {
+        const paperId = input.paperId.trim();
+        if (paperId === '')
+            throw new SearchError('bad_request', 'paperId 不能为空');
+        if (!known.has(paperId)) {
+            throw new SearchError('bad_request', `任务里没有这篇文献：${paperId}`);
+        }
+        const next = { ...(states[paperId] ?? emptyState()) };
+        let touched = false;
+        if (input.screening !== undefined) {
+            if (!isScreening(input.screening)) {
+                throw new SearchError('bad_request', `screening 只能是 ${SCREENINGS.join(' / ')}`);
+            }
+            next.screening = input.screening;
+            touched = true;
+        }
+        if (input.groupId !== undefined) {
+            if (input.groupId === null || input.groupId === '') {
+                delete next.groupId;
+            }
+            else {
+                if (!groupIds.has(input.groupId)) {
+                    throw new SearchError('bad_request', `未知分组：${input.groupId}`);
+                }
+                next.groupId = input.groupId;
+            }
+            touched = true;
+        }
+        if (input.shortlistOrder !== undefined) {
+            if (input.shortlistOrder === null) {
+                delete next.shortlistOrder;
+            }
+            else {
+                if (!Number.isInteger(input.shortlistOrder) ||
+                    input.shortlistOrder < 0 ||
+                    input.shortlistOrder > MAX_SHORTLIST_ORDER) {
+                    throw new SearchError('bad_request', `shortlistOrder 必须是 0..${MAX_SHORTLIST_ORDER} 的整数`);
+                }
+                next.shortlistOrder = input.shortlistOrder;
+            }
+            touched = true;
+        }
+        if (input.note !== undefined) {
+            if (typeof input.note !== 'string')
+                throw new SearchError('bad_request', 'note 必须是字符串');
+            const note = input.note.trim();
+            if (note === '')
+                delete next.note;
+            else
+                next.note = note.slice(0, MAX_NOTE);
+            touched = true;
+        }
+        if (input.tags !== undefined) {
+            if (!Array.isArray(input.tags))
+                throw new SearchError('bad_request', 'tags 必须是字符串数组');
+            const tags = normalizeTags(input.tags);
+            if (tags.length === 0)
+                delete next.tags;
+            else
+                next.tags = tags;
+            touched = true;
+        }
+        if (input.pdfStatus !== undefined) {
+            if (!isPdfStatus(input.pdfStatus)) {
+                throw new SearchError('bad_request', `pdfStatus 只能是 ${PDF_STATUSES.join(' / ')}`);
+            }
+            next.pdfStatus = input.pdfStatus;
+            touched = true;
+        }
+        if (input.pdfError !== undefined) {
+            if (typeof input.pdfError !== 'string') {
+                throw new SearchError('bad_request', 'pdfError 必须是字符串');
+            }
+            const reason = input.pdfError.trim();
+            if (reason === '')
+                delete next.pdfError;
+            else
+                next.pdfError = reason.slice(0, MAX_PDF_ERROR);
+            touched = true;
+        }
+        if (input.pdfFile !== undefined) {
+            if (typeof input.pdfFile !== 'string') {
+                throw new SearchError('bad_request', 'pdfFile 必须是字符串');
+            }
+            const file = input.pdfFile.trim();
+            if (file === '')
+                delete next.pdfFile;
+            else
+                next.pdfFile = file.slice(0, MAX_PDF_FILE);
+            touched = true;
+        }
+        if (!touched)
+            continue;
+        states[paperId] = next;
+        updated += 1;
+    }
+    return { states, updated };
+}
+/** 校验分组列表：id 唯一、名称非空、顺序重排为连续整数。 */
+export function normalizeGroups(values) {
+    if (values === undefined)
+        return undefined;
+    if (!Array.isArray(values))
+        throw new SearchError('bad_request', 'groups 必须是数组');
+    if (values.length > MAX_GROUPS) {
+        throw new SearchError('bad_request', `分组最多 ${MAX_GROUPS} 个`);
+    }
+    const seen = new Set();
+    const groups = [];
+    for (const raw of values) {
+        const id = raw.id.trim();
+        if (id === '' || id.length > 40) {
+            throw new SearchError('bad_request', '分组 id 必须是 1..40 个字符');
+        }
+        if (seen.has(id))
+            throw new SearchError('bad_request', `分组 id 重复：${id}`);
+        seen.add(id);
+        const name = raw.name.trim();
+        if (name === '')
+            throw new SearchError('bad_request', '分组名称不能为空');
+        const group = {
+            id,
+            name: name.slice(0, MAX_GROUP_NAME),
+            order: groups.length,
+        };
+        const description = raw.description?.trim() ?? '';
+        if (description !== '')
+            group.description = description.slice(0, MAX_GROUP_DESCRIPTION);
+        groups.push(group);
+    }
+    return groups;
+}
+/** 分组若仍有论文引用，删除前提醒调用方（调用方决定是否允许）。 */
+export function groupUsage(task, groupId) {
+    return Object.values(task.states).filter((state) => state.groupId === groupId).length;
+}
+/** 按必读顺序、年份、标题排序某组的论文。 */
+export function sortGroupPapers(task, papers) {
+    return [...papers].sort((a, b) => {
+        const left = stateOf(task, a.paperId).shortlistOrder;
+        const right = stateOf(task, b.paperId).shortlistOrder;
+        if (left !== undefined || right !== undefined) {
+            if (left === undefined)
+                return 1;
+            if (right === undefined)
+                return -1;
+            if (left !== right)
+                return left - right;
+        }
+        return (b.year ?? 0) - (a.year ?? 0) || a.title.localeCompare(b.title);
+    });
+}
+function normalizeTags(values) {
+    const seen = new Set();
+    for (const raw of values) {
+        const tag = raw.trim().slice(0, MAX_TAG);
+        if (tag !== '')
+            seen.add(tag);
+        if (seen.size >= MAX_TAGS)
+            break;
+    }
+    return [...seen];
+}

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

@@ -0,0 +1,13 @@
+/**
+ * 任务概览统计。
+ *
+ * 只统计**已加载**的结果（任务最多 1500 篇，内存聚合毫秒级），并复用
+ * `filter.ts` 的筛选口径，保证列表与统计一致。结果按 `rev + 口径 + 筛选指纹`
+ * 缓存 30 秒，追加/重跑后 rev 变化自动失效。
+ */
+import type { SearchTask, TaskStatsReport } from '../../search/types.js';
+import { type PaperFilter } from './filter.js';
+export declare function computeStats(task: SearchTask, filter: PaperFilter, scope: 'task' | 'filtered', base?: {
+    paperIds: ReadonlySet<string>;
+    rev: number;
+}): TaskStatsReport;

package/lib/host/tasks/stats.js

@@ -0,0 +1,233 @@
+/**
+ * 任务概览统计。
+ *
+ * 只统计**已加载**的结果（任务最多 1500 篇，内存聚合毫秒级），并复用
+ * `filter.ts` 的筛选口径，保证列表与统计一致。结果按 `rev + 口径 + 筛选指纹`
+ * 缓存 30 秒，追加/重跑后 rev 变化自动失效。
+ */
+import { filterKey, filterPapers, pdfStatusOf, screeningOf } from './filter.js';
+const CACHE_TTL_MS = 30_000;
+const CACHE_MAX = 16;
+const TOP_LIST = 15;
+const TOP_PAPERS = 10;
+const cache = new Map();
+export function computeStats(task, filter, scope, base) {
+    const key = `${task.id}:${task.rev}:${scope}:${filterKey(filter)}:${base?.rev ?? ''}`;
+    const cached = cache.get(key);
+    if (cached !== undefined && Date.now() - cached.at < CACHE_TTL_MS)
+        return cached.report;
+    const report = buildReport(task, filter, scope, base);
+    cache.set(key, { at: Date.now(), report });
+    if (cache.size > CACHE_MAX) {
+        const oldest = cache.keys().next().value;
+        if (oldest !== undefined)
+            cache.delete(oldest);
+    }
+    return report;
+}
+function buildReport(task, filter, scope, base) {
+    const all = task.result.papers;
+    const papers = scope === 'filtered' ? filterPapers(task, filter) : all;
+    const included = papers.filter((paper) => screeningOf(task, paper) === 'included').length;
+    const excluded = papers.filter((paper) => screeningOf(task, paper) === 'excluded').length;
+    const read = papers.filter((paper) => screeningOf(task, paper) === 'read').length;
+    const unread = papers.length - included - excluded - read;
+    const fullText = countFullText(task, papers);
+    return {
+        taskId: task.id,
+        rev: task.rev,
+        scope,
+        loaded: papers.length,
+        totalHint: all.length,
+        funnel: {
+            rawHits: task.stats.rawHits,
+            deduped: task.stats.deduped,
+            filtered: papers.length,
+            included,
+            excluded,
+            unread,
+            read,
+        },
+        bySource: buildSourceStats(task, papers),
+        byQuery: buildQueryStats(task, papers),
+        byYear: buildYearStats(task, papers),
+        byType: countBy(task, papers, (paper) => paper.type),
+        byLanguage: countBy(task, papers, (paper) => paper.language ?? ''),
+        topVenues: topBy(task, papers, (paper) => (paper.venue === '' ? [] : [paper.venue])),
+        topAuthors: topBy(task, papers, (paper) => paper.authors),
+        metrics: buildMetrics(papers, base),
+        screeningProgress: { included, excluded, pending: unread },
+        unavailableFullText: {
+            paywalled: fullText.paywalled,
+            blocked: fullText.blocked,
+            failed: fullText.failed,
+        },
+        fullText,
+    };
+}
+function countFullText(task, papers) {
+    const coverage = {
+        unknown: 0,
+        available: 0,
+        downloaded: 0,
+        htmlOnly: 0,
+        paywalled: 0,
+        blocked: 0,
+        failed: 0,
+    };
+    for (const paper of papers) {
+        const status = pdfStatusOf(task, paper);
+        if (status === 'html-only')
+            coverage.htmlOnly += 1;
+        else if (status === 'available')
+            coverage.available += 1;
+        else if (status === 'downloaded')
+            coverage.downloaded += 1;
+        else if (status === 'paywalled')
+            coverage.paywalled += 1;
+        else if (status === 'blocked')
+            coverage.blocked += 1;
+        else if (status === 'failed')
+            coverage.failed += 1;
+        else
+            coverage.unknown += 1;
+    }
+    return coverage;
+}
+function buildSourceStats(task, papers) {
+    const ids = new Set(task.conditions.sources);
+    for (const paper of papers) {
+        for (const hit of paper.hitSources)
+            ids.add(hit.source);
+    }
+    return task.conditions.sources
+        .filter((id) => ids.has(id))
+        .map((id) => {
+        const hits = papers.filter((paper) => paper.hitSources.some((hit) => hit.source === id));
+        return {
+            id,
+            hits: hits.length,
+            uniqueOnly: hits.filter((paper) => paper.hitSources.length === 1).length,
+            oa: hits.filter((paper) => paper.openAccess).length,
+            withPdf: hits.filter((paper) => paper.pdfUrl !== '').length,
+        };
+    });
+}
+function buildQueryStats(task, papers) {
+    const queryIds = task.conditions.queries.map((query) => query.id);
+    const overlap = new Map();
+    for (const id of queryIds) {
+        overlap.set(id, new Map(queryIds.filter((other) => other !== id).map((other) => [other, 0])));
+    }
+    for (const paper of papers) {
+        const matched = paper.matchedQueries.filter((id) => overlap.has(id));
+        for (const left of matched) {
+            for (const right of matched) {
+                if (left === right)
+                    continue;
+                const row = overlap.get(left);
+                if (row === undefined)
+                    continue;
+                row.set(right, (row.get(right) ?? 0) + 1);
+            }
+        }
+    }
+    return task.conditions.queries.map((query) => {
+        const uniqueOnly = papers.filter((paper) => paper.matchedQueries.length === 1 && paper.matchedQueries[0] === query.id).length;
+        const row = overlap.get(query.id);
+        return {
+            queryId: query.id,
+            name: query.name,
+            hits: task.stats.perQuery[query.id] ?? 0,
+            uniqueOnly,
+            overlap: row === undefined ? {} : Object.fromEntries(row),
+        };
+    });
+}
+function buildYearStats(task, papers) {
+    const years = new Map();
+    for (const paper of papers) {
+        if (paper.year === null)
+            continue;
+        const entry = years.get(paper.year) ?? { count: 0, included: 0 };
+        entry.count += 1;
+        if (screeningOf(task, paper) === 'included')
+            entry.included += 1;
+        years.set(paper.year, entry);
+    }
+    return [...years.entries()]
+        .map(([year, entry]) => ({ year, ...entry }))
+        .sort((a, b) => a.year - b.year);
+}
+function countBy(task, papers, keyOf) {
+    const counts = new Map();
+    for (const paper of papers) {
+        const key = keyOf(paper).trim();
+        if (key === '')
+            continue;
+        const entry = counts.get(key) ?? { count: 0, included: 0 };
+        entry.count += 1;
+        if (screeningOf(task, paper) === 'included')
+            entry.included += 1;
+        counts.set(key, entry);
+    }
+    return [...counts.entries()]
+        .map(([key, entry]) => ({ key, ...entry }))
+        .sort((a, b) => b.count - a.count);
+}
+function topBy(task, papers, keysOf) {
+    const counts = new Map();
+    for (const paper of papers) {
+        const included = screeningOf(task, paper) === 'included';
+        for (const value of keysOf(paper)) {
+            const key = value.trim();
+            if (key === '')
+                continue;
+            const entry = counts.get(key) ?? { count: 0, included: 0 };
+            entry.count += 1;
+            if (included)
+                entry.included += 1;
+            counts.set(key, entry);
+        }
+    }
+    return [...counts.entries()]
+        .map(([key, entry]) => ({ key, ...entry }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, TOP_LIST);
+}
+function buildMetrics(papers, base) {
+    const total = papers.length;
+    const oa = papers.filter((paper) => paper.openAccess).length;
+    const pdf = papers.filter((paper) => paper.pdfUrl !== '').length;
+    const htmlOnly = papers.filter((paper) => paper.openAccess && paper.pdfUrl === '').length;
+    const citations = papers
+        .map((paper) => paper.citedBy)
+        .filter((value) => value !== null)
+        .sort((a, b) => a - b);
+    const median = citations.length === 0
+        ? 0
+        : citations.length % 2 === 1
+            ? citations[(citations.length - 1) / 2]
+            : Math.round((citations[citations.length / 2 - 1] + citations[citations.length / 2]) / 2);
+    return {
+        oaRate: total === 0 ? 0 : round(oa / total),
+        pdfRate: total === 0 ? 0 : round(pdf / total),
+        htmlOnlyRate: total === 0 ? 0 : round(htmlOnly / total),
+        medianCitations: median,
+        topCited: [...papers]
+            .filter((paper) => paper.citedBy !== null)
+            .sort((a, b) => (b.citedBy ?? 0) - (a.citedBy ?? 0))
+            .slice(0, TOP_PAPERS)
+            .map((paper) => paper.paperId),
+        latest: [...papers]
+            .sort((a, b) => (b.year ?? 0) - (a.year ?? 0))
+            .slice(0, TOP_PAPERS)
+            .map((paper) => paper.paperId),
+        ...(base === undefined
+            ? {}
+            : { newVsBase: papers.filter((paper) => !base.paperIds.has(paper.paperId)).length }),
+    };
+}
+function round(value) {
+    return Math.round(value * 1000) / 1000;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * 任务持久化：`<root>/tasks/<id>.json` + `tasks/index.json`。
+ *
+ * - 数据根目录为 `$DSH_HOME/storages/dsh-plugin-litsearch`（见 `host/paths.ts`），
+ *   加载时若新目录为空而旧目录有任务，会一次性复制过来；显式传入 root 时不迁移；
+ * - 写盘全部串行执行，先写临时文件再 rename，避免半截 JSON；
+ * - 内存里只保留摘要，任务正文按需从磁盘读；
+ * - 落盘时摘要截到 {@link MAX_ABSTRACT_CHARS} 字符，任务数按保留策略裁剪。
+ */
+import type { SearchTask, TaskSummary } from '../../search/types.js';
+export interface RetentionOptions {
+    retentionDays: number;
+    retentionCount: number;
+}
+/** 「当前任务」快照：最近一次使用或打开的任务。 */
+export interface CurrentTaskSnapshot {
+    version: number;
+    current?: {
+        taskId: string;
+        at: number;
+    };
+}
+export declare class TaskStore {
+    root: string;
+    private tasksDir;
+    private indexFile;
+    private currentFile;
+    private readonly summaries;
+    private readonly cache;
+    private chain;
+    private retention;
+    /** 只有使用默认（平台统一）目录时才做旧数据迁移；显式 root 多用于测试。 */
+    private readonly migrateOnLoad;
+    /** 迁移过来的任务文件必须重建索引，避免沿用旧目录里那份空 index.json。 */
+    private forceRebuildIndex;
+    constructor(root?: string);
+    load(retention: RetentionOptions): Promise<void>;
+    list(): TaskSummary[];
+    summary(id: string): TaskSummary | undefined;
+    /** 同步取已缓存任务；未加载时返回 undefined。 */
+    cached(id: string): SearchTask | undefined;
+    loadTask(id: string): Promise<SearchTask | undefined>;
+    put(task: SearchTask): void;
+    save(task: SearchTask): Promise<void>;
+    remove(id: string): Promise<void>;
+    flush(): Promise<void>;
+    /** 读取「当前任务」快照；文件缺失或损坏时返回 null（由调用方自举）。 */
+    loadCurrent(): Promise<CurrentTaskSnapshot | null>;
+    saveCurrent(snapshot: CurrentTaskSnapshot): Promise<void>;
+    /** 手动清理：删除所有未置顶任务，返回条数与释放的字节数。 */
+    cleanupUnpinned(): Promise<{
+        removed: number;
+        freedBytes: number;
+    }>;
+    /** 迁移回退时切回旧目录读取，所有派生路径（含设置页展示）同步更新。 */
+    private rebind;
+    private taskFile;
+    private readIndex;
+    /** 索引缺失/损坏时按任务文件重建（只读头部，不长期占内存）。 */
+    private rebuildIndex;
+    private prune;
+    private writeIndex;
+    private enqueue;
+}