dsh-plugin-litsearch 0.0.0-stage → 0.2.0

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh bundle patch：把本插件插入 profile 层栈。
+#
+# - 模型侧工具由本插件自持：直接在 Host 进程内调用免费文献 API
+#   （OpenAlex、Crossref…），再以 `literature_*` 名称注册进 dsh 工具表。
+#   因此不需要插入任何 MCP client 行。
+# - 人侧检索界面由 Client 半注册右侧栏 tab，并通过本插件在宿主 web server
+#   上注册的 `/dsh-litsearch/api/*` 端点读写任务。
+- insert:
+    - id: dsh-plugin-litsearch
+      name: dsh-plugin-litsearch

package/lib/host/events.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 任务变更事件日志。
+ *
+ * Host→Client 没有原生广播通道，因此这里只维护一份「最近一次状态 + 单调递增
+ * 的 globalRev」日志；客户端按 `sinceRev` 轮询拿增量。globalRev 只在宿主进程内
+ * 单调递增，重启后归零 —— 客户端发现 `sinceRev` 比服务端大就以 `reset` 重新同步。
+ */
+import type { EventsPage, TaskSummary } from '../search/types.js';
+export declare class TaskEvents {
+    private rev;
+    private readonly entries;
+    private focus;
+    get currentRev(): number;
+    publish(summary: TaskSummary): void;
+    /** 请求客户端把某个任务 tab 打开/切到前台（面板关着时重新打开）。 */
+    requestFocus(taskId: string, title: string, sessionId?: string): void;
+    remove(id: string): void;
+    since(sinceRev: number): EventsPage;
+}

package/lib/host/events.js

@@ -0,0 +1,58 @@
+/**
+ * 任务变更事件日志。
+ *
+ * Host→Client 没有原生广播通道，因此这里只维护一份「最近一次状态 + 单调递增
+ * 的 globalRev」日志；客户端按 `sinceRev` 轮询拿增量。globalRev 只在宿主进程内
+ * 单调递增，重启后归零 —— 客户端发现 `sinceRev` 比服务端大就以 `reset` 重新同步。
+ */
+export class TaskEvents {
+    rev = 0;
+    entries = new Map();
+    focus;
+    get currentRev() {
+        return this.rev;
+    }
+    publish(summary) {
+        this.rev += 1;
+        this.entries.set(summary.id, { globalRev: this.rev, summary });
+    }
+    /** 请求客户端把某个任务 tab 打开/切到前台（面板关着时重新打开）。 */
+    requestFocus(taskId, title, sessionId) {
+        this.rev += 1;
+        this.focus = {
+            globalRev: this.rev,
+            taskId,
+            title,
+            at: Date.now(),
+            ...(sessionId === undefined ? {} : { sessionId }),
+        };
+    }
+    remove(id) {
+        this.entries.delete(id);
+        if (this.focus?.taskId === id)
+            this.focus = undefined;
+    }
+    since(sinceRev) {
+        if (!Number.isFinite(sinceRev) || sinceRev < 0) {
+            return { rev: this.rev, reset: true, tasks: [] };
+        }
+        if (sinceRev > this.rev) {
+            return { rev: this.rev, reset: true, tasks: [] };
+        }
+        const tasks = [...this.entries.values()]
+            .filter((entry) => entry.globalRev > sinceRev)
+            .sort((a, b) => a.globalRev - b.globalRev)
+            .map((entry) => entry.summary);
+        const focus = this.focus !== undefined && this.focus.globalRev > sinceRev
+            ? {
+                taskId: this.focus.taskId,
+                title: this.focus.title,
+                at: this.focus.at,
+                ...(this.focus.sessionId === undefined
+                    ? {}
+                    : { sessionId: this.focus.sessionId }),
+            }
+            : undefined;
+        return { rev: this.rev, reset: false, tasks, ...(focus === undefined ? {} : { focus }) };
+    }
+}

package/lib/host/export/bibtex.d.ts

@@ -0,0 +1,3 @@
+/** BibTeX 导出。 */
+import type { ExportContext } from './common.js';
+export declare function renderBibtex(context: ExportContext): string;

package/lib/host/export/bibtex.js

@@ -0,0 +1,42 @@
+/** BibTeX 导出。 */
+import { groupName, paperNote } from './common.js';
+import { stateOf } from '../tasks/states.js';
+export function renderBibtex(context) {
+    return `${context.papers
+        .map((paper) => {
+        const state = stateOf(context.task, paper.paperId);
+        const fields = [];
+        fields.push(['title', paper.title]);
+        if (paper.authors.length > 0)
+            fields.push(['author', paper.authors.join(' and ')]);
+        if (paper.year !== null)
+            fields.push(['year', String(paper.year)]);
+        if (paper.venue !== '')
+            fields.push(['journal', paper.venue]);
+        if (paper.doi !== '')
+            fields.push(['doi', paper.doi]);
+        if (paper.url !== '')
+            fields.push(['url', paper.url]);
+        if (paper.abstract !== '')
+            fields.push(['abstract', paper.abstract]);
+        const group = groupName(context.task, state.groupId);
+        if (group !== '')
+            fields.push(['keywords', group]);
+        const note = paperNote(context.task, paper);
+        if (note !== '')
+            fields.push(['note', note]);
+        const body = fields
+            .map(([name, value]) => `  ${name} = {${escapeBibtex(value)}}`)
+            .join(',\n');
+        return `@article{${paper.paperId},\n${body}\n}`;
+    })
+        .join('\n\n')}\n`;
+}
+function escapeBibtex(value) {
+    return value
+        .replace(/\\/gu, '\\\\')
+        .replace(/[{}]/gu, (match) => `\\${match}`)
+        .replace(/[&%$#_]/gu, (match) => `\\${match}`)
+        .replace(/~/gu, '\\textasciitilde{}')
+        .replace(/\^/gu, '\\textasciicircum{}');
+}

package/lib/host/export/common.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 导出共用上下文：把任务、待导出论文与可选的对比基准打包给各格式渲染器。
+ */
+import type { Paper, SearchTask } from '../../search/types.js';
+export interface ExportContext {
+    task: SearchTask;
+    papers: Paper[];
+    /** `markdown` 导出用于生成「与对比任务差异」区块。 */
+    base?: SearchTask;
+    generatedAt: Date;
+}
+export declare function queryName(task: SearchTask, queryId: string): string;
+export declare function groupName(task: SearchTask, groupId: string | undefined): string;
+export declare function paperNote(task: SearchTask, paper: Paper): string;
+export declare function paperTags(task: SearchTask, paper: Paper): string[];
+export declare function isoDate(date: Date): string;
+/** 文件名用的安全任务 id（导出统一按 id 命名，避免标题里的路径字符）。 */
+export declare function exportStem(task: SearchTask, date: Date): string;

package/lib/host/export/common.js

@@ -0,0 +1,25 @@
+/**
+ * 导出共用上下文：把任务、待导出论文与可选的对比基准打包给各格式渲染器。
+ */
+import { stateOf } from '../tasks/states.js';
+export function queryName(task, queryId) {
+    return task.conditions.queries.find((query) => query.id === queryId)?.name ?? queryId;
+}
+export function groupName(task, groupId) {
+    if (groupId === undefined)
+        return '';
+    return task.groups.find((group) => group.id === groupId)?.name ?? '';
+}
+export function paperNote(task, paper) {
+    return stateOf(task, paper.paperId).note ?? '';
+}
+export function paperTags(task, paper) {
+    return stateOf(task, paper.paperId).tags ?? [];
+}
+export function isoDate(date) {
+    return date.toISOString().slice(0, 10);
+}
+/** 文件名用的安全任务 id（导出统一按 id 命名，避免标题里的路径字符）。 */
+export function exportStem(task, date) {
+    return `litsearch-${task.id}-${isoDate(date)}`;
+}

package/lib/host/export/csv.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 全量筛读台账 CSV。
+ *
+ * 列顺序与第一版方案一致，后续全文能力只需填 `pdfStatus` / `pdfError`，不改列。
+ * 带 UTF-8 BOM，方便 Excel 直接打开中文。
+ */
+import type { ExportContext } from './common.js';
+export declare function renderCsv(context: ExportContext): string;

package/lib/host/export/csv.js

@@ -0,0 +1,68 @@
+/**
+ * 全量筛读台账 CSV。
+ *
+ * 列顺序与第一版方案一致，后续全文能力只需填 `pdfStatus` / `pdfError`，不改列。
+ * 带 UTF-8 BOM，方便 Excel 直接打开中文。
+ */
+import { groupName, paperNote, queryName } from './common.js';
+import { pdfStatusOf } from '../tasks/filter.js';
+import { stateOf } from '../tasks/states.js';
+const COLUMNS = [
+    'paperId',
+    'title',
+    'authors',
+    'year',
+    'venue',
+    'doi',
+    'pmid',
+    'pmcid',
+    'arxivId',
+    'sources',
+    'matchedQueries',
+    'citedBy',
+    'openAccess',
+    'language',
+    'screening',
+    'group',
+    'shortlistOrder',
+    'pdfStatus',
+    'pdfError',
+    'note',
+];
+export function renderCsv(context) {
+    const { task, papers } = context;
+    const lines = [COLUMNS.join(',')];
+    for (const paper of papers) {
+        const state = stateOf(task, paper.paperId);
+        lines.push([
+            paper.paperId,
+            paper.title,
+            paper.authors.join('; '),
+            paper.year === null ? '' : String(paper.year),
+            paper.venue,
+            paper.doi,
+            paper.ids.pmid,
+            paper.ids.pmcid,
+            paper.ids.arxivId,
+            paper.hitSources.map((hit) => hit.source).join(';'),
+            paper.matchedQueries.map((id) => queryName(task, id)).join(';'),
+            paper.citedBy === null ? '' : String(paper.citedBy),
+            paper.openAccess ? '1' : '0',
+            paper.language ?? '',
+            state.screening,
+            groupName(task, state.groupId),
+            state.shortlistOrder === undefined ? '' : String(state.shortlistOrder),
+            pdfStatusOf(task, paper),
+            state.pdfError ?? '',
+            paperNote(task, paper),
+        ]
+            .map(csvCell)
+            .join(','));
+    }
+    return `\uFEFF${lines.join('\r\n')}\r\n`;
+}
+function csvCell(value) {
+    if (!/[",\r\n]/u.test(value))
+        return value;
+    return `"${value.replace(/"/gu, '""')}"`;
+}

package/lib/host/export/index.d.ts

@@ -0,0 +1,5 @@
+/** 导出格式分发：把同一个上下文渲染成 CSV / RIS / BibTeX / Markdown。 */
+import type { ExportFile, ExportFormat } from '../../search/types.js';
+import type { ExportContext } from './common.js';
+export type { ExportContext } from './common.js';
+export declare function buildExport(context: ExportContext, format: ExportFormat): ExportFile;

package/lib/host/export/index.js

@@ -0,0 +1,25 @@
+/** 导出格式分发：把同一个上下文渲染成 CSV / RIS / BibTeX / Markdown。 */
+import { renderBibtex } from './bibtex.js';
+import { exportStem } from './common.js';
+import { renderCsv } from './csv.js';
+import { renderMarkdown } from './markdown.js';
+import { renderRis } from './ris.js';
+const MIME = {
+    csv: 'text/csv; charset=utf-8',
+    ris: 'application/x-research-info-systems; charset=utf-8',
+    bibtex: 'application/x-bibtex; charset=utf-8',
+    md: 'text/markdown; charset=utf-8',
+};
+export function buildExport(context, format) {
+    const stem = exportStem(context.task, context.generatedAt);
+    switch (format) {
+        case 'csv':
+            return { filename: `${stem}.csv`, mime: MIME.csv, content: renderCsv(context) };
+        case 'ris':
+            return { filename: `${stem}.ris`, mime: MIME.ris, content: renderRis(context) };
+        case 'bibtex':
+            return { filename: `${stem}.bib`, mime: MIME.bibtex, content: renderBibtex(context) };
+        default:
+            return { filename: `${stem}.md`, mime: MIME.md, content: renderMarkdown(context) };
+    }
+}

package/lib/host/export/markdown.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Markdown 检索报告：检索式组（可复现）、规模漏斗、分组阅读清单、必读路线、
+ * 对比差异与研究笔记。结构对齐两份真实产出。
+ */
+import type { ExportContext } from './common.js';
+export declare function renderMarkdown(context: ExportContext): string;

package/lib/host/export/markdown.js

@@ -0,0 +1,120 @@
+/**
+ * Markdown 检索报告：检索式组（可复现）、规模漏斗、分组阅读清单、必读路线、
+ * 对比差异与研究笔记。结构对齐两份真实产出。
+ */
+import { compareTasks } from '../tasks/compare.js';
+import { sortGroupPapers, stateOf } from '../tasks/states.js';
+import { isoDate } from './common.js';
+const TOP_COMPARE = 30;
+const TOP_ROUTE = 30;
+export function renderMarkdown(context) {
+    const { task, papers, base, generatedAt } = context;
+    const lines = [];
+    lines.push(`# ${task.title}`, '');
+    lines.push(`- 任务 id：${task.id}`);
+    lines.push(`- 检索日期：${isoDate(new Date(task.result.fetchedAt ?? task.createdAt))}`);
+    lines.push(`- 报告生成：${isoDate(generatedAt)}`);
+    lines.push(`- 数据源：${task.conditions.sources.join('、')}`);
+    lines.push(`- 规模：原始命中 ${task.stats.rawHits} 条，去重 ${task.stats.deduped} 篇，已加载 ${task.result.papers.length} 篇`);
+    const counts = countStates(context);
+    lines.push(`- 筛读：纳入 ${counts.included} 篇，排除 ${counts.excluded} 篇，已读 ${counts.read} 篇，未读 ${counts.unread} 篇`);
+    if (base !== undefined) {
+        const diff = compareTasks(task, base);
+        lines.push(`- 对比「${base.title}」：新增 ${diff.counts.added} 篇，共有 ${diff.counts.common} 篇，缺失 ${diff.counts.missing} 篇`);
+    }
+    lines.push('');
+    lines.push('## 检索式组（可复现）', '');
+    task.conditions.queries.forEach((query, index) => {
+        lines.push(`${index + 1}. **${query.name}**：\`${query.text}\` — 原始命中 ${task.stats.perQuery[query.id] ?? 0} 条`);
+        const overrides = Object.entries(query.perSource ?? {});
+        if (overrides.length > 0) {
+            lines.push(`   - 单源覆写：${overrides.map(([source, text]) => `${source}=\`${text}\``).join('；')}`);
+        }
+    });
+    lines.push('');
+    lines.push('## 分组阅读清单', '');
+    for (const group of task.groups) {
+        const items = papers.filter((paper) => stateOf(task, paper.paperId).groupId === group.id);
+        lines.push(`### ${group.name}（${items.length} 篇）`, '');
+        if (group.description !== undefined && group.description !== '') {
+            lines.push(group.description, '');
+        }
+        if (items.length === 0) {
+            lines.push('_（暂无文献）_', '');
+        }
+        else {
+            lines.push('| # | 文献 | 年份 / 出处 | 为什么读 | 状态 |');
+            lines.push('|---:|---|---|---|---|');
+            sortGroupPapers(task, items).forEach((paper, index) => {
+                lines.push(`| ${index + 1} | ${paperLabel(paper)} | ${metaLabel(paper)} | ${cell(stateOf(task, paper.paperId).note ?? '')} | ${stateOf(task, paper.paperId).screening} |`);
+            });
+            lines.push('');
+        }
+    }
+    const ungrouped = papers.filter((paper) => stateOf(task, paper.paperId).groupId === undefined);
+    if (ungrouped.length > 0) {
+        lines.push(`### 未分组（${ungrouped.length} 篇）`, '');
+        lines.push('| # | 文献 | 年份 / 出处 | 为什么读 | 状态 |');
+        lines.push('|---:|---|---|---|---|');
+        ungrouped.slice(0, 120).forEach((paper, index) => {
+            lines.push(`| ${index + 1} | ${paperLabel(paper)} | ${metaLabel(paper)} | ${cell(stateOf(task, paper.paperId).note ?? '')} | ${stateOf(task, paper.paperId).screening} |`);
+        });
+        if (ungrouped.length > 120)
+            lines.push('', `_（仅列出前 120 篇，完整清单见 CSV）_`);
+        lines.push('');
+    }
+    const route = papers
+        .filter((paper) => stateOf(task, paper.paperId).shortlistOrder !== undefined)
+        .sort((a, b) => (stateOf(task, a.paperId).shortlistOrder ?? 0) -
+        (stateOf(task, b.paperId).shortlistOrder ?? 0))
+        .slice(0, TOP_ROUTE);
+    lines.push('## 必读阅读路线', '');
+    if (route.length === 0) {
+        lines.push('_（尚未标记必读顺序）_', '');
+    }
+    else {
+        route.forEach((paper, index) => {
+            const note = stateOf(task, paper.paperId).note;
+            lines.push(`${index + 1}. ${paperLabel(paper)}${note === undefined ? '' : ` — ${note}`}`);
+        });
+        lines.push('');
+    }
+    lines.push('## 全文获取情况', '');
+    const oa = papers.filter((paper) => paper.openAccess).length;
+    const pdf = papers.filter((paper) => paper.pdfUrl !== '').length;
+    lines.push(`- 开放获取 ${oa} 篇，PDF 直链 ${pdf} 篇，其余 ${papers.length - oa} 篇需自行获取。`);
+    lines.push('');
+    if (base !== undefined) {
+        const diff = compareTasks(task, base);
+        lines.push(`## 与对比任务差异`, '');
+        lines.push(`基准任务：${base.title}（${diff.counts.baseTotal} 篇）。新增 ${diff.counts.added} 篇，共有 ${diff.counts.common} 篇，缺失 ${diff.counts.missing} 篇。`, '');
+        diff.added.slice(0, TOP_COMPARE).forEach((paper, index) => {
+            lines.push(`${index + 1}. ${paper.title}${paper.year === null ? '' : `（${paper.year}）`}`);
+        });
+        if (diff.added.length > TOP_COMPARE) {
+            lines.push('', `_（仅列出前 ${TOP_COMPARE} 篇新增）_`);
+        }
+        lines.push('');
+    }
+    lines.push('## 研究笔记', '');
+    lines.push(task.notes.trim() === '' ? '_（暂无）_' : task.notes.trim(), '');
+    return lines.join('\n');
+}
+function countStates(context) {
+    const counts = { unread: 0, read: 0, included: 0, excluded: 0 };
+    for (const paper of context.papers) {
+        counts[stateOf(context.task, paper.paperId).screening] += 1;
+    }
+    return counts;
+}
+function paperLabel(paper) {
+    const text = cell(paper.title);
+    return paper.doi === '' ? text : `[${text}](https://doi.org/${paper.doi})`;
+}
+function metaLabel(paper) {
+    const year = paper.year === null ? '' : String(paper.year);
+    return cell([year, paper.venue].filter((part) => part !== '').join(' / '));
+}
+function cell(value) {
+    return value.trim().replace(/\|/gu, '\\|').replace(/\r?\n/gu, ' ');
+}

package/lib/host/export/ris.d.ts

@@ -0,0 +1,3 @@
+/** RIS 导出（供 Zotero / EndNote 导入）。 */
+import type { ExportContext } from './common.js';
+export declare function renderRis(context: ExportContext): string;

package/lib/host/export/ris.js

@@ -0,0 +1,35 @@
+/** RIS 导出（供 Zotero / EndNote 导入）。 */
+import { groupName, paperNote, paperTags } from './common.js';
+import { stateOf } from '../tasks/states.js';
+export function renderRis(context) {
+    const blocks = context.papers.map((paper) => {
+        const state = stateOf(context.task, paper.paperId);
+        const lines = ['TY  - JOUR'];
+        push(lines, 'TI', paper.title);
+        for (const author of paper.authors)
+            push(lines, 'AU', author);
+        if (paper.year !== null)
+            push(lines, 'PY', String(paper.year));
+        push(lines, 'JO', paper.venue);
+        push(lines, 'DO', paper.doi);
+        push(lines, 'UR', paper.pdfUrl !== '' ? paper.pdfUrl : paper.url);
+        push(lines, 'AB', paper.abstract);
+        push(lines, 'AN', paper.paperId);
+        const group = groupName(context.task, state.groupId);
+        if (group !== '')
+            push(lines, 'KW', group);
+        for (const tag of paperTags(context.task, paper))
+            push(lines, 'KW', tag);
+        push(lines, 'N1', paperNote(context.task, paper));
+        if (state.screening !== 'unread')
+            push(lines, 'N1', `screening: ${state.screening}`);
+        lines.push('ER  - ');
+        return lines.join('\r\n');
+    });
+    return `${blocks.join('\r\n\r\n')}\r\n`;
+}
+function push(lines, tag, value) {
+    if (value.trim() === '')
+        return;
+    lines.push(`${tag}  - ${value.replace(/\r?\n/gu, ' ')}`);
+}

package/lib/host/paths.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 插件数据目录解析与旧版数据迁移。
+ *
+ * 平台约定：插件私有数据统一放在 `$DSH_HOME/storages/<plugin-id>/`，
+ * `DSH_HOME` 由宿主注入，未设置时回落 `~/.dsh`。本插件历史版本把数据直接
+ * 写在 `~/.dsh/dsh-litsearch/`，这里负责一次性搬迁到统一存储区：
+ *
+ * - 只复制、不删除，旧目录原样保留作备份；
+ * - 不覆盖新目录里已有的文件，重复启动不会反复迁移；
+ * - 复制失败或校验不通过时回退到旧目录读取，保证任务标注不丢。
+ *
+ * PDF 的可读文件由设置项 `pdfRoot` 决定（默认 `~/Downloads/dsh-litsearch`），
+ * 不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs` 随数据目录一起搬迁。
+ */
+export declare const PLUGIN_ID = "dsh-plugin-litsearch";
+/** 历史版本使用的目录名（`$DSH_HOME` 下的一级目录）。 */
+export declare const LEGACY_DIR = "dsh-litsearch";
+/** 解析宿主数据根目录；支持绝对路径、`~/...` 与空值回落。 */
+export declare function dshHome(env?: NodeJS.ProcessEnv, home?: string): string;
+/** 当前数据根目录：平台统一存储区下的插件域。 */
+export declare function storageRoot(env?: NodeJS.ProcessEnv, home?: string): string;
+/** 旧数据根目录候选，按优先级排列，已排除新根目录。 */
+export declare function legacyRoots(env?: NodeJS.ProcessEnv, home?: string): string[];
+/** 目录里是否存在至少一个任务正文文件（索引与快照不算）。 */
+export declare function hasTaskFiles(root: string): Promise<boolean>;
+export interface StorageResolution {
+    /** 最终使用的数据根目录。 */
+    root: string;
+    /** 本次复制的文件数。 */
+    copied: number;
+    /** 从该旧目录迁移成功。 */
+    migratedFrom?: string;
+    /** 迁移失败，暂时回退到该旧目录读取。 */
+    fallbackFrom?: string;
+}
+/**
+ * 决定最终数据根目录，并在必要时做一次性迁移：
+ *
+ * 1. 新目录已有任务 → 直接使用，绝不碰旧数据；
+ * 2. 新目录为空且旧目录有任务 → 复制缺失文件到新目录，旧目录保留；
+ * 3. 复制失败或复制后仍无任务 → 回滚本次副本并回退到旧目录读取。
+ */
+export declare function resolveStorageRoot(env?: NodeJS.ProcessEnv, home?: string): Promise<StorageResolution>;

package/lib/host/paths.js

@@ -0,0 +1,128 @@
+/**
+ * 插件数据目录解析与旧版数据迁移。
+ *
+ * 平台约定：插件私有数据统一放在 `$DSH_HOME/storages/<plugin-id>/`，
+ * `DSH_HOME` 由宿主注入，未设置时回落 `~/.dsh`。本插件历史版本把数据直接
+ * 写在 `~/.dsh/dsh-litsearch/`，这里负责一次性搬迁到统一存储区：
+ *
+ * - 只复制、不删除，旧目录原样保留作备份；
+ * - 不覆盖新目录里已有的文件，重复启动不会反复迁移；
+ * - 复制失败或校验不通过时回退到旧目录读取，保证任务标注不丢。
+ *
+ * PDF 的可读文件由设置项 `pdfRoot` 决定（默认 `~/Downloads/dsh-litsearch`），
+ * 不受本模块影响；只有插件内部的去重缓存 `<root>/pdfs` 随数据目录一起搬迁。
+ */
+import { copyFile, mkdir, readdir, rm, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+export const PLUGIN_ID = 'dsh-plugin-litsearch';
+/** 历史版本使用的目录名（`$DSH_HOME` 下的一级目录）。 */
+export const LEGACY_DIR = 'dsh-litsearch';
+/** 允许搬迁的条目：任务正文与索引、导出文件、PDF 去重缓存、当前任务快照。 */
+const MIGRATABLE_ENTRIES = ['tasks', 'out', 'pdfs', 'current.json'];
+/** 解析宿主数据根目录；支持绝对路径、`~/...` 与空值回落。 */
+export function dshHome(env = process.env, home = homedir()) {
+    const raw = env.DSH_HOME?.trim() ?? '';
+    if (raw === '')
+        return join(home, '.dsh');
+    if (raw === '~')
+        return home;
+    if (raw.startsWith('~/'))
+        return join(home, raw.slice(2));
+    // 绝对路径原样规范化，相对路径按进程工作目录解析（与宿主 path.resolve 一致）。
+    return resolve(raw);
+}
+/** 当前数据根目录：平台统一存储区下的插件域。 */
+export function storageRoot(env = process.env, home = homedir()) {
+    return join(dshHome(env, home), 'storages', PLUGIN_ID);
+}
+/** 旧数据根目录候选，按优先级排列，已排除新根目录。 */
+export function legacyRoots(env = process.env, home = homedir()) {
+    const current = storageRoot(env, home);
+    const candidates = [
+        join(dshHome(env, home), LEGACY_DIR), // 过渡形态：$DSH_HOME/dsh-litsearch
+        join(home, '.dsh', LEGACY_DIR), // 历史硬编码：~/.dsh/dsh-litsearch
+    ];
+    return [...new Set(candidates)].filter((path) => path !== current);
+}
+/** 目录里是否存在至少一个任务正文文件（索引与快照不算）。 */
+export async function hasTaskFiles(root) {
+    const names = await readdir(join(root, 'tasks')).catch(() => []);
+    return names.some((name) => name.endsWith('.json') && name !== 'index.json');
+}
+/**
+ * 决定最终数据根目录，并在必要时做一次性迁移：
+ *
+ * 1. 新目录已有任务 → 直接使用，绝不碰旧数据；
+ * 2. 新目录为空且旧目录有任务 → 复制缺失文件到新目录，旧目录保留；
+ * 3. 复制失败或复制后仍无任务 → 回滚本次副本并回退到旧目录读取。
+ */
+export async function resolveStorageRoot(env = process.env, home = homedir()) {
+    const root = storageRoot(env, home);
+    if (await hasTaskFiles(root))
+        return { root, copied: 0 };
+    for (const legacy of legacyRoots(env, home)) {
+        if (!(await hasTaskFiles(legacy)))
+            continue;
+        const copied = [];
+        try {
+            await copyLegacyStorage(legacy, root, copied);
+            if (await hasTaskFiles(root)) {
+                console.info(`[dsh-plugin-litsearch] 任务数据已迁移：${legacy} → ${root}（${copied.length} 个文件，原目录保留）`);
+                return { root, migratedFrom: legacy, copied: copied.length };
+            }
+            await rollback(copied);
+        }
+        catch (error) {
+            await rollback(copied);
+            console.warn('[dsh-plugin-litsearch] 任务数据迁移失败：', error);
+        }
+        console.warn(`[dsh-plugin-litsearch] 暂时沿用旧任务目录：${legacy}`);
+        return { root: legacy, fallbackFrom: legacy, copied: 0 };
+    }
+    return { root, copied: 0 };
+}
+/** 复制旧目录里的已知条目；目标已存在则跳过，复制路径写入 `copied` 供回滚。 */
+async function copyLegacyStorage(from, to, copied) {
+    for (const entry of MIGRATABLE_ENTRIES) {
+        const source = join(from, entry);
+        const target = join(to, entry);
+        const info = await stat(source).catch(() => null);
+        if (info === null)
+            continue;
+        if (info.isFile()) {
+            await copyFileIfAbsent(source, target, copied);
+        }
+        else if (info.isDirectory()) {
+            await copyDirIfAbsent(source, target, copied);
+        }
+    }
+}
+async function copyDirIfAbsent(source, target, copied) {
+    const entries = await readdir(source, { withFileTypes: true });
+    for (const entry of entries) {
+        // 跳过原子写残留的临时文件与系统杂项。
+        if (entry.name.startsWith('.') || entry.name.endsWith('.tmp'))
+            continue;
+        const from = join(source, entry.name);
+        const to = join(target, entry.name);
+        if (entry.isDirectory()) {
+            await copyDirIfAbsent(from, to, copied);
+        }
+        else if (entry.isFile()) {
+            await copyFileIfAbsent(from, to, copied);
+        }
+    }
+}
+async function copyFileIfAbsent(source, target, copied) {
+    if ((await stat(target).catch(() => null)) !== null)
+        return;
+    await mkdir(dirname(target), { recursive: true });
+    await copyFile(source, target);
+    copied.push(target);
+}
+/** 迁移未完成时清掉本次副本，让下次启动可以重新迁移（源文件始终不动）。 */
+async function rollback(files) {
+    for (const file of files)
+        await rm(file, { force: true }).catch(() => { });
+}