dsh-plugin-litsearch 0.0.0-stage → 0.2.0

package/lib/host/tasks/store.js

@@ -0,0 +1,280 @@
+/**
+ * 任务持久化：`<root>/tasks/<id>.json` + `tasks/index.json`。
+ *
+ * - 数据根目录为 `$DSH_HOME/storages/dsh-plugin-litsearch`（见 `host/paths.ts`），
+ *   加载时若新目录为空而旧目录有任务，会一次性复制过来；显式传入 root 时不迁移；
+ * - 写盘全部串行执行，先写临时文件再 rename，避免半截 JSON；
+ * - 内存里只保留摘要，任务正文按需从磁盘读；
+ * - 落盘时摘要截到 {@link MAX_ABSTRACT_CHARS} 字符，任务数按保留策略裁剪。
+ */
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { MAX_ABSTRACT_CHARS } from '../../search/config.js';
+import { resolveStorageRoot, storageRoot } from '../paths.js';
+import { cloneRound, roundsOf, toSummary, trimRounds } from './summary.js';
+const INDEX_VERSION = 1;
+export class TaskStore {
+    root;
+    tasksDir;
+    indexFile;
+    currentFile;
+    summaries = new Map();
+    cache = new Map();
+    chain = Promise.resolve();
+    retention = { retentionDays: 90, retentionCount: 120 };
+    /** 只有使用默认（平台统一）目录时才做旧数据迁移；显式 root 多用于测试。 */
+    migrateOnLoad;
+    /** 迁移过来的任务文件必须重建索引，避免沿用旧目录里那份空 index.json。 */
+    forceRebuildIndex = false;
+    constructor(root) {
+        this.migrateOnLoad = root === undefined;
+        this.root = root ?? storageRoot();
+        this.tasksDir = join(this.root, 'tasks');
+        this.indexFile = join(this.tasksDir, 'index.json');
+        this.currentFile = join(this.root, 'current.json');
+    }
+    async load(retention) {
+        this.retention = retention;
+        if (this.migrateOnLoad) {
+            try {
+                const resolution = await resolveStorageRoot();
+                this.rebind(resolution.root);
+                // 复制过来的 index.json 可能不含新任务，强制按任务文件重建一次。
+                this.forceRebuildIndex = resolution.migratedFrom !== undefined;
+            }
+            catch (error) {
+                // 目录解析失败不应阻断任务系统启动，继续用构造时的默认目录。
+                console.warn('[dsh-plugin-litsearch] 数据目录解析失败，沿用默认目录：', error);
+            }
+        }
+        await mkdir(this.tasksDir, { recursive: true });
+        const index = this.forceRebuildIndex ? null : await this.readIndex();
+        if (index === null) {
+            await this.rebuildIndex();
+        }
+        else {
+            for (const summary of index.tasks)
+                this.summaries.set(summary.id, summary);
+        }
+        await this.prune();
+    }
+    list() {
+        return [...this.summaries.values()].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    summary(id) {
+        return this.summaries.get(id);
+    }
+    /** 同步取已缓存任务；未加载时返回 undefined。 */
+    cached(id) {
+        return this.cache.get(id);
+    }
+    async loadTask(id) {
+        const cached = this.cache.get(id);
+        if (cached !== undefined)
+            return cached;
+        if (this.summaries.get(id) === undefined)
+            return undefined;
+        try {
+            const text = await readFile(this.taskFile(id), 'utf8');
+            const parsed = JSON.parse(text);
+            if (parsed.task === undefined) {
+                await this.remove(id);
+                return undefined;
+            }
+            // 旧版本任务文件没有 rounds；统一补齐并裁掉超限轮次，避免历史无限增长。
+            parsed.task.rounds = trimRounds(roundsOf(parsed.task));
+            this.cache.set(id, parsed.task);
+            return parsed.task;
+        }
+        catch {
+            await this.remove(id);
+            return undefined;
+        }
+    }
+    put(task) {
+        this.cache.set(task.id, task);
+        this.summaries.set(task.id, toSummary(task));
+    }
+    async save(task) {
+        // 运行中的任务可能被用户删除：删除后的迟到落盘会重建文件与索引，这里直接丢弃。
+        if (!this.summaries.has(task.id))
+            return;
+        this.put(task);
+        const file = this.taskFile(task.id);
+        const body = JSON.stringify({ version: INDEX_VERSION, task: truncateForDisk(task) });
+        await this.enqueue(async () => {
+            await atomicWrite(file, body);
+            await this.writeIndex();
+        });
+    }
+    async remove(id) {
+        this.cache.delete(id);
+        this.summaries.delete(id);
+        await this.enqueue(async () => {
+            await rm(this.taskFile(id), { force: true });
+            await this.writeIndex();
+        });
+    }
+    async flush() {
+        await this.chain;
+    }
+    /** 读取「当前任务」快照；文件缺失或损坏时返回 null（由调用方自举）。 */
+    async loadCurrent() {
+        try {
+            const parsed = JSON.parse(await readFile(this.currentFile, 'utf8'));
+            const current = readBinding(parsed.current);
+            return { version: INDEX_VERSION, ...(current === undefined ? {} : { current }) };
+        }
+        catch {
+            return null;
+        }
+    }
+    async saveCurrent(snapshot) {
+        const body = JSON.stringify(snapshot);
+        await this.enqueue(async () => {
+            await atomicWrite(this.currentFile, body);
+        });
+    }
+    /** 手动清理：删除所有未置顶任务，返回条数与释放的字节数。 */
+    async cleanupUnpinned() {
+        const targets = this.list().filter((summary) => !summary.pinned);
+        let freedBytes = 0;
+        for (const summary of targets) {
+            try {
+                freedBytes += (await stat(this.taskFile(summary.id))).size;
+            }
+            catch {
+                // 文件已丢失时仍继续移除索引项。
+            }
+            await this.remove(summary.id);
+        }
+        return { removed: targets.length, freedBytes };
+    }
+    /** 迁移回退时切回旧目录读取，所有派生路径（含设置页展示）同步更新。 */
+    rebind(root) {
+        if (root === this.root)
+            return;
+        this.root = root;
+        this.tasksDir = join(root, 'tasks');
+        this.indexFile = join(this.tasksDir, 'index.json');
+        this.currentFile = join(root, 'current.json');
+    }
+    taskFile(id) {
+        return join(this.tasksDir, `${id}.json`);
+    }
+    async readIndex() {
+        try {
+            const parsed = JSON.parse(await readFile(this.indexFile, 'utf8'));
+            if (!Array.isArray(parsed.tasks))
+                return null;
+            return { version: INDEX_VERSION, tasks: parsed.tasks };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 索引缺失/损坏时按任务文件重建（只读头部，不长期占内存）。 */
+    async rebuildIndex() {
+        let names;
+        try {
+            names = await readdir(this.tasksDir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (!name.endsWith('.json') || name === 'index.json')
+                continue;
+            const id = name.slice(0, -'.json'.length);
+            if (this.summaries.has(id))
+                continue;
+            try {
+                const parsed = JSON.parse(await readFile(join(this.tasksDir, name), 'utf8'));
+                if (parsed.task !== undefined)
+                    this.summaries.set(parsed.task.id, toSummary(parsed.task));
+            }
+            catch {
+                // 损坏的任务文件直接跳过，索引里不再保留它。
+            }
+        }
+        await this.writeIndex();
+    }
+    async prune() {
+        const now = Date.now();
+        let kept = 0;
+        const expire = [];
+        for (const summary of this.list()) {
+            if (summary.pinned)
+                continue;
+            const ageDays = (now - Date.parse(summary.updatedAt)) / 86_400_000;
+            if (kept >= this.retention.retentionCount || ageDays > this.retention.retentionDays) {
+                expire.push(summary.id);
+            }
+            else {
+                kept += 1;
+            }
+        }
+        for (const id of expire)
+            await this.remove(id);
+    }
+    async writeIndex() {
+        const index = { version: INDEX_VERSION, tasks: this.list() };
+        await atomicWrite(this.indexFile, JSON.stringify(index));
+    }
+    enqueue(operation) {
+        const next = this.chain.then(operation, operation);
+        this.chain = next.catch((error) => {
+            console.warn('[dsh-plugin-litsearch] 任务写盘失败：', error);
+        });
+        return this.chain;
+    }
+}
+async function atomicWrite(file, body) {
+    await mkdir(dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(temp, body, 'utf8');
+    await rename(temp, file);
+}
+function readBinding(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    if (typeof record.taskId !== 'string' || record.taskId === '')
+        return undefined;
+    return { taskId: record.taskId, at: typeof record.at === 'number' ? record.at : 0 };
+}
+function truncateForDisk(task) {
+    return {
+        ...task,
+        conditions: {
+            ...task.conditions,
+            queries: task.conditions.queries.map((query) => ({ ...query })),
+            sources: [...task.conditions.sources],
+        },
+        groups: task.groups.map((group) => ({ ...group })),
+        stats: {
+            perQuery: { ...task.stats.perQuery },
+            rawHits: task.stats.rawHits,
+            deduped: task.stats.deduped,
+            screening: { ...task.stats.screening },
+        },
+        states: { ...task.states },
+        // 轮次只记元数据；显式深拷贝，避免与内存任务共享条件引用。
+        rounds: trimRounds(roundsOf(task)).map(cloneRound),
+        result: {
+            ...task.result,
+            sources: task.result.sources.map((source) => ({ ...source })),
+            papers: task.result.papers.map(truncatePaper),
+        },
+    };
+}
+function truncatePaper(paper) {
+    return {
+        ...paper,
+        abstract: paper.abstract.length <= MAX_ABSTRACT_CHARS
+            ? paper.abstract
+            : `${paper.abstract.slice(0, MAX_ABSTRACT_CHARS)}…`,
+        hitSources: paper.hitSources.map((hit) => ({ ...hit })),
+        matchedQueries: [...paper.matchedQueries],
+    };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * 任务序列化投影：历史列表与事件只传摘要，详情不含结果正文。
+ */
+import type { SearchRound, SearchTask, TaskSummary, TaskDetail } from '../../search/types.js';
+export { cloneConditions, cloneRound, roundsOf } from './rounds.js';
+/** 按插件配置裁剪轮次（纯逻辑在 rounds.ts，上限在这里注入）。 */
+export declare function trimRounds(rounds: SearchRound[]): SearchRound[];
+export declare function toSummary(task: SearchTask): TaskSummary;
+export declare function toDetail(task: SearchTask): TaskDetail;

package/lib/host/tasks/summary.js

@@ -0,0 +1,54 @@
+/**
+ * 任务序列化投影：历史列表与事件只传摘要，详情不含结果正文。
+ */
+import { DEFAULT_TASK_MAX_ROUNDS } from '../../search/config.js';
+import { cloneConditions, cloneRound, roundsOf, trimRoundList } from './rounds.js';
+export { cloneConditions, cloneRound, roundsOf } from './rounds.js';
+/** 按插件配置裁剪轮次（纯逻辑在 rounds.ts，上限在这里注入）。 */
+export function trimRounds(rounds) {
+    return trimRoundList(rounds, DEFAULT_TASK_MAX_ROUNDS);
+}
+export function toSummary(task) {
+    return {
+        id: task.id,
+        title: task.title,
+        status: task.status,
+        origin: task.origin,
+        createdAt: task.createdAt,
+        updatedAt: task.updatedAt,
+        rev: task.rev,
+        pinned: task.pinned,
+        stats: cloneStats(task.stats),
+        roundCount: roundsOf(task).length,
+        ...(task.progress === undefined ? {} : { progress: { ...task.progress } }),
+        ...(task.error === undefined ? {} : { error: task.error }),
+    };
+}
+export function toDetail(task) {
+    const states = {};
+    for (const [paperId, state] of Object.entries(task.states)) {
+        states[paperId] = { ...state, ...(state.tags === undefined ? {} : { tags: [...state.tags] }) };
+    }
+    return {
+        ...toSummary(task),
+        conditions: cloneConditions(task.conditions),
+        notes: task.notes,
+        groups: task.groups.map((group) => ({ ...group })),
+        rounds: roundsOf(task).map(cloneRound),
+        states,
+        ...(task.fromTaskId === undefined ? {} : { fromTaskId: task.fromTaskId }),
+        result: {
+            totalLoaded: task.result.papers.length,
+            sources: task.result.sources.map((source) => ({ ...source })),
+            ...(task.result.fetchedAt === undefined ? {} : { fetchedAt: task.result.fetchedAt }),
+        },
+    };
+}
+function cloneStats(stats) {
+    return {
+        perQuery: { ...stats.perQuery },
+        rawHits: stats.rawHits,
+        deduped: stats.deduped,
+        screening: { ...stats.screening },
+    };
+}

package/lib/host/tools.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 模型侧工具：直接注册进 dsh 工具表（不经过外部 MCP）。
+ *
+ * - `literature_search`：一个研究主题 = 一个任务 = 一个 tab。默认复用「当前
+ *   任务」并在其中开新一轮（当前任务是持久化的最近使用任务，跨对话、宿主重启
+ *   都有效）；只有用户明确要求新任务时才新建。等待最多 25 秒后把任务头部与前
+ *   若干条结果交给模型，并明确要求本轮到此为止、只给完善建议、不发起下一轮。
+ * - `literature_sources`：列出已接入的数据源与能力，便于模型决定后续策略。
+ * - `literature_task`：读取/修改已保存任务（含轮次历史），写入筛读、分组与备注，
+ *   做新老对比与统计。
+ * - `literature_export`：把任务（按筛选）导出为 CSV / RIS / BibTeX / Markdown 并落盘。
+ *
+ * 参数在边界做一次校验（模型输出不可信），服务层仍会再兜底。
+ */
+import type { TaskService } from './tasks/service.js';
+/** `ctx.tools` 的最小结构接口（真实类型由 dsh 装配，不在本包类型面内）。 */
+export interface ToolsService {
+    register(definition: unknown): () => void;
+}
+/** 执行时附带的上下文：取消信号 + 发起调用的会话。 */
+interface ToolRunExec {
+    signal?: AbortSignal;
+    /** 当前会话；用于把聚焦请求送回发起检索的那个对话。 */
+    agent?: {
+        id: string;
+    };
+}
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    output: {
+        schema: Record<string, unknown>;
+        render: (args: unknown, value: {
+            text: string;
+        }) => Array<{
+            type: 'text';
+            text: string;
+        }>;
+    };
+    execute: (args: unknown, exec: ToolRunExec) => Promise<{
+        text: string;
+    }>;
+}
+/** 构造本插件注册的全部工具（每次注册都新造定义，便于整体替换）。 */
+export declare function literatureTools(service: TaskService): ToolDefinition[];
+export {};