dsh-plugin-litsearch 0.3.0 → 0.4.0

package/lib/host/zotero/connector.d.ts

@@ -4,11 +4,15 @@
  * 只允许回环地址：connector 是桌面端本地服务，绝不把用户数据发到外部主机。
  * 任何失败都转成可读的一句话，由调用方汇总成「未运行 / 条目保存失败 / 附件失败」。
  */
-import type { Paper, ZoteroProbeResult, ZoteroSyncResult } from '../../search/types.js';
+import type { Paper, ZoteroProbeResult, ZoteroSyncResult, ZoteroTargetsResult } from '../../search/types.js';
 export interface ZoteroConnectorOptions {
     baseUrl: string;
     attachPdf: boolean;
     tag: string;
+    /** connector 的 treeViewID（如 `C15`）；缺省沿用 Zotero 当前选中的目录。 */
+    targetId?: string;
+    /** 目标目录名，仅用于失败提示。 */
+    targetName?: string;
 }
 export interface ZoteroSyncInput {
     paper: Paper;
@@ -20,8 +24,13 @@ export declare class ZoteroConnector {
     private readonly baseUrl;
     constructor(baseUrl: string);
     probe(): Promise<ZoteroProbeResult>;
-    /** 当前 Zotero 里选中的分类；未选中时返回 null。 */
-    selectedCollection(): Promise<SelectedCollection | null>;
+    /** 所有可写入的库与分类，供同步弹窗选择目标。 */
+    listTargets(): Promise<ZoteroTargetsResult>;
+    /**
+     * `/connector/getSelectedCollection` 只接受 POST，返回当前目标与全部可写目标。
+     * 注意 GET 会直接 400，因此不能沿用 ping 的方式。
+     */
+    private fetchTargetInfo;
     /**
      * 保存条目并可选上传本地 PDF。
      *
@@ -29,6 +38,13 @@ export declare class ZoteroConnector {
      * messages，条目仍算保存成功。
      */
     sync(inputs: readonly ZoteroSyncInput[], options: ZoteroConnectorOptions): Promise<ZoteroSyncResult>;
+    /**
+     * 把本会话已保存的条目移动到指定目标。
+     *
+     * `tags` 传空数组：saveItems 用 `forceTagType: 1` 写入的标签是自动标签，
+     * updateSession 会保留自动标签；传空数组可避免同名标签重复写入。
+     */
+    private moveToTarget;
     /**
      * 保存条目。Zotero 返回 201 空响应，条目 id 由请求里的 `id` 字段决定，
      * 后续 `saveAttachment` 用它作为 parentItemID，并复用同一 sessionID。
@@ -37,10 +53,3 @@ export declare class ZoteroConnector {
     private saveAttachment;
     private request;
 }
-interface SelectedCollection {
-    id: number | string;
-    name: string;
-    libraryID?: number;
-    filesEditable?: boolean;
-}
-export {};

package/lib/host/zotero/connector.js

@@ -44,7 +44,8 @@ export class ZoteroConnector {
                 return { ok: false, error: `connector 返回 HTTP ${response.status}` };
             }
             const version = response.headers.get('x-zotero-version') ?? undefined;
-            const collection = await this.selectedCollection().catch(() => null);
+            const info = await this.fetchTargetInfo().catch(() => null);
+            const collection = info === null ? null : selectedOf(info);
             const result = { ok: true };
             if (version !== undefined)
                 result.version = version;
@@ -64,29 +65,43 @@ export class ZoteroConnector {
             return { ok: false, error: describe(error) };
         }
     }
-    /** 当前 Zotero 里选中的分类；未选中时返回 null。 */
-    async selectedCollection() {
+    /** 所有可写入的库与分类，供同步弹窗选择目标。 */
+    async listTargets() {
+        try {
+            const info = await this.fetchTargetInfo();
+            const targets = [];
+            for (const raw of info.targets ?? []) {
+                const target = toTarget(raw);
+                if (target !== null)
+                    targets.push(target);
+            }
+            const selected = selectedOf(info);
+            const result = { ok: true, targets };
+            if (selected !== null)
+                result.current = { id: selected.treeViewID, name: selected.name };
+            return result;
+        }
+        catch (error) {
+            return { ok: false, targets: [], error: describe(error) };
+        }
+    }
+    /**
+     * `/connector/getSelectedCollection` 只接受 POST，返回当前目标与全部可写目标。
+     * 注意 GET 会直接 400，因此不能沿用 ping 的方式。
+     */
+    async fetchTargetInfo() {
         const response = await this.request('/connector/getSelectedCollection', {
-            method: 'GET',
+            method: 'POST',
             timeoutMs: PING_TIMEOUT_MS,
+            headers: { 'content-type': 'application/json' },
+            body: '{}',
         });
         if (!response.ok)
-            return null;
+            throw new Error(`connector 返回 HTTP ${response.status}`);
         const body = (await response.json().catch(() => null));
-        if (body === null || body === false || typeof body !== 'object')
-            return null;
-        const record = body;
-        const id = record['id'];
-        const name = record['name'];
-        if ((typeof id !== 'number' && typeof id !== 'string') || typeof name !== 'string')
-            return null;
-        const collection = { id, name };
-        if (typeof record['libraryID'] === 'number')
-            collection.libraryID = record['libraryID'];
-        if (typeof record['filesEditable'] === 'boolean') {
-            collection.filesEditable = record['filesEditable'];
-        }
-        return collection;
+        if (body === null || typeof body !== 'object')
+            throw new Error('connector 返回空响应');
+        return body;
     }
     /**
      * 保存条目并可选上传本地 PDF。
@@ -95,49 +110,93 @@ export class ZoteroConnector {
      * messages，条目仍算保存成功。
      */
     async sync(inputs, options) {
-        if (inputs.length === 0)
-            return { ok: true, saved: 0, attached: 0, failed: 0, messages: [] };
-        if (inputs.length > MAX_SYNC_ITEMS) {
-            throw new Error(`一次最多同步 ${MAX_SYNC_ITEMS} 篇`);
-        }
         const result = {
             ok: true,
             saved: 0,
             attached: 0,
             failed: 0,
             messages: [],
+            items: [],
         };
+        if (inputs.length === 0)
+            return result;
+        if (inputs.length > MAX_SYNC_ITEMS) {
+            throw new Error(`一次最多同步 ${MAX_SYNC_ITEMS} 篇`);
+        }
         for (const input of inputs) {
             const sessionID = newSessionID();
             const item = toZoteroItem(input.paper, input.tags, options.tag);
             try {
                 await this.saveItem(item, sessionID);
-                result.saved += 1;
             }
             catch (error) {
+                const reason = describe(error);
                 result.failed += 1;
-                result.messages.push(`${shortTitle(input.paper.title)}：条目保存失败（${describe(error)}）`);
+                result.messages.push(`${shortTitle(input.paper.title)}：条目保存失败（${reason}）`);
+                result.items.push({ paperId: input.paper.paperId, ok: false, attached: false, error: reason });
                 continue;
             }
-            if (!options.attachPdf || input.pdfPath === undefined)
-                continue;
-            const parentId = typeof item['id'] === 'string' ? item['id'] : null;
-            if (parentId === null) {
-                result.messages.push(`${shortTitle(input.paper.title)}：条目已保存，但缺少条目 id，未上传 PDF`);
-                continue;
-            }
-            try {
-                const buffer = await readFile(input.pdfPath);
-                await this.saveAttachment(parentId, sessionID, input.paper, buffer);
-                result.attached += 1;
+            // 条目先落到 Zotero 当前选中的目录，再用 updateSession 搬到用户选的目录。
+            if (options.targetId !== undefined) {
+                try {
+                    await this.moveToTarget(sessionID, options.targetId);
+                }
+                catch (error) {
+                    const targetName = options.targetName ?? options.targetId;
+                    const reason = `未能移入「${targetName}」（${describe(error)}）`;
+                    result.failed += 1;
+                    result.messages.push(`${shortTitle(input.paper.title)}：条目已保存，但${reason}`);
+                    result.items.push({
+                        paperId: input.paper.paperId,
+                        ok: false,
+                        attached: false,
+                        error: reason,
+                    });
+                    continue;
+                }
             }
-            catch (error) {
-                result.messages.push(`${shortTitle(input.paper.title)}：PDF 附件失败（${describe(error)}）`);
+            result.saved += 1;
+            let attached = false;
+            if (options.attachPdf && input.pdfPath !== undefined) {
+                const parentId = typeof item['id'] === 'string' ? item['id'] : null;
+                if (parentId === null) {
+                    result.messages.push(`${shortTitle(input.paper.title)}：条目已保存，但缺少条目 id，未上传 PDF`);
+                }
+                else {
+                    try {
+                        const buffer = await readFile(input.pdfPath);
+                        await this.saveAttachment(parentId, sessionID, input.paper, buffer);
+                        result.attached += 1;
+                        attached = true;
+                    }
+                    catch (error) {
+                        result.messages.push(`${shortTitle(input.paper.title)}：PDF 附件失败（${describe(error)}）`);
+                    }
+                }
             }
+            result.items.push({ paperId: input.paper.paperId, ok: true, attached });
         }
         result.ok = result.failed === 0;
         return result;
     }
+    /**
+     * 把本会话已保存的条目移动到指定目标。
+     *
+     * `tags` 传空数组：saveItems 用 `forceTagType: 1` 写入的标签是自动标签，
+     * updateSession 会保留自动标签；传空数组可避免同名标签重复写入。
+     */
+    async moveToTarget(sessionID, target) {
+        const response = await this.request('/connector/updateSession', {
+            method: 'POST',
+            timeoutMs: SAVE_TIMEOUT_MS,
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ sessionID, target, tags: [] }),
+        });
+        if (!response.ok) {
+            const detail = (await response.text().catch(() => '')).slice(0, 120);
+            throw new Error(`connector 返回 HTTP ${response.status}${detail === '' ? '' : `（${detail}）`}`);
+        }
+    }
     /**
      * 保存条目。Zotero 返回 201 空响应，条目 id 由请求里的 `id` 字段决定，
      * 后续 `saveAttachment` 用它作为 parentItemID，并复用同一 sessionID。
@@ -201,6 +260,50 @@ export class ZoteroConnector {
         }
     }
 }
+/** 当前选中目标。未选中分类时 `id` 为 null，用 libraryID 组成 `L<n>`。 */
+function selectedOf(info) {
+    if (typeof info.name !== 'string')
+        return null;
+    const libraryID = typeof info.libraryID === 'number' ? info.libraryID : undefined;
+    let treeViewID;
+    if (typeof info.id === 'number')
+        treeViewID = `C${info.id}`;
+    else if (typeof info.id === 'string' && isTargetId(info.id))
+        treeViewID = info.id;
+    else if (libraryID !== undefined)
+        treeViewID = `L${libraryID}`;
+    else
+        return null;
+    const selected = {
+        id: typeof info.id === 'number' || typeof info.id === 'string' ? info.id : treeViewID,
+        name: info.name,
+        treeViewID,
+    };
+    if (libraryID !== undefined)
+        selected.libraryID = libraryID;
+    if (typeof info.filesEditable === 'boolean')
+        selected.filesEditable = info.filesEditable;
+    return selected;
+}
+function toTarget(raw) {
+    if (typeof raw.id !== 'string' || typeof raw.name !== 'string')
+        return null;
+    if (!isTargetId(raw.id))
+        return null;
+    const target = {
+        id: raw.id,
+        name: raw.name,
+        level: typeof raw.level === 'number' ? raw.level : 0,
+    };
+    if (typeof raw.filesEditable === 'boolean')
+        target.filesEditable = raw.filesEditable;
+    if (raw.recent === true)
+        target.recent = true;
+    return target;
+}
+function isTargetId(value) {
+    return /^[LC]\d+$/u.test(value);
+}
 function toZoteroItem(paper, tags, defaultTag) {
     const item = {
         id: paper.paperId,

package/lib/host/zotero/match.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 把模型从对话里听到的「存到 xx 目录」匹配到 Zotero connector 的真实目标。
+ *
+ * 纯函数、只做类型导入：`src` 源码可被 `node --test` 直接加载，Host 构建
+ * 产物仍走 `.js`。匹配失败或歧义时绝不猜一个目录就写入数据 —— 同步会真的
+ * 往 Zotero 里建条目，猜错代价太高。
+ */
+import type { ZoteroTarget } from '../../search/types.js';
+export type ZoteroMatch = {
+    kind: 'matched';
+    target: ZoteroTarget;
+} | {
+    kind: 'ambiguous';
+    candidates: ZoteroTarget[];
+} | {
+    kind: 'none';
+    candidates: ZoteroTarget[];
+};
+/**
+ * 匹配顺序：id 精确 → 名称精确（忽略大小写与空白）→ 名称包含。
+ *
+ * 任何一步命中多个都算歧义，返回候选让模型在对话里向用户确认；只有唯一
+ * 命中才返回 `matched`，由工具带上 `autoStart` 让右侧栏直接开跑。
+ */
+export declare function matchZoteroTarget(targets: readonly ZoteroTarget[], query: string): ZoteroMatch;
+/** 给模型的可用目录清单（工具返回文本里让用户/模型确认用）。 */
+export declare function describeZoteroTargets(targets: readonly ZoteroTarget[], limit?: number): string;

package/lib/host/zotero/match.js

@@ -0,0 +1,59 @@
+/**
+ * 把模型从对话里听到的「存到 xx 目录」匹配到 Zotero connector 的真实目标。
+ *
+ * 纯函数、只做类型导入：`src` 源码可被 `node --test` 直接加载，Host 构建
+ * 产物仍走 `.js`。匹配失败或歧义时绝不猜一个目录就写入数据 —— 同步会真的
+ * 往 Zotero 里建条目，猜错代价太高。
+ */
+const MAX_CANDIDATES = 8;
+/** 归一化：去首尾空白、合并连续空白（含全角空格）、忽略大小写。 */
+function normalize(value) {
+    return value.trim().replace(/\s+/gu, ' ').toLowerCase();
+}
+function candidatesOf(targets) {
+    // 目录多时优先给用户常看的：最近使用过的排前面，其余保持 connector 原序。
+    return [
+        ...targets.filter((target) => target.recent === true),
+        ...targets.filter((target) => target.recent !== true),
+    ].slice(0, MAX_CANDIDATES);
+}
+/**
+ * 匹配顺序：id 精确 → 名称精确（忽略大小写与空白）→ 名称包含。
+ *
+ * 任何一步命中多个都算歧义，返回候选让模型在对话里向用户确认；只有唯一
+ * 命中才返回 `matched`，由工具带上 `autoStart` 让右侧栏直接开跑。
+ */
+export function matchZoteroTarget(targets, query) {
+    const needle = normalize(query);
+    if (needle === '')
+        return { kind: 'none', candidates: candidatesOf(targets) };
+    const byId = targets.filter((target) => target.id.toLowerCase() === needle);
+    if (byId.length === 1)
+        return { kind: 'matched', target: byId[0] };
+    if (byId.length > 1)
+        return { kind: 'ambiguous', candidates: candidatesOf(byId) };
+    const byName = targets.filter((target) => normalize(target.name) === needle);
+    if (byName.length === 1)
+        return { kind: 'matched', target: byName[0] };
+    if (byName.length > 1)
+        return { kind: 'ambiguous', candidates: candidatesOf(byName) };
+    const partial = targets.filter((target) => normalize(target.name).includes(needle));
+    if (partial.length === 1)
+        return { kind: 'matched', target: partial[0] };
+    if (partial.length > 1)
+        return { kind: 'ambiguous', candidates: candidatesOf(partial) };
+    return { kind: 'none', candidates: candidatesOf(targets) };
+}
+/** 给模型的可用目录清单（工具返回文本里让用户/模型确认用）。 */
+export function describeZoteroTargets(targets, limit = 12) {
+    if (targets.length === 0)
+        return '（Zotero 里没有可用目录）';
+    const lines = targets.slice(0, limit).map((target) => {
+        const indent = '  '.repeat(Math.max(0, target.level));
+        const suffix = target.filesEditable === false ? '（不可写附件）' : '';
+        return `- ${indent}${target.name}${suffix}（id: ${target.id}）`;
+    });
+    if (targets.length > limit)
+        lines.push(`- ……还有 ${targets.length - limit} 个目录`);
+    return lines.join('\n');
+}

package/lib/search/config.d.ts

@@ -5,8 +5,6 @@
  * 保存配置后无需重启即生效。
  */
 import type { SortMode, SourceId, TaskLanguage } from './types.js';
-/** 插件版本（与 package.json 同步；仅用于 /health 诊断展示）。 */
-export declare const PLUGIN_VERSION = "0.1.0";
 /**
  * 默认数据源。
  *

package/lib/search/config.js

@@ -5,8 +5,6 @@
  * 保存配置后无需重启即生效。
  */
 import { SOURCE_IDS } from './types.js';
-/** 插件版本（与 package.json 同步；仅用于 /health 诊断展示）。 */
-export const PLUGIN_VERSION = '0.1.0';
 /**
  * 默认数据源。
  *

package/lib/search/oa.d.ts

@@ -6,6 +6,14 @@
 import type { Paper } from './types.js';
 /** 去重后的 PDF 候选地址（顺序即尝试优先级）。 */
 export declare function pdfCandidates(paper: Paper): string[];
+/**
+ * 仓储的 PDF 渲染页：浏览器能打开，后台请求却普遍被拦截。
+ *
+ * 实测 `europepmc.org/articles/...?pdf=render` 返回 403 Cloudflare 页、
+ * `ncbi.nlm.nih.gov/pmc/articles/.../pdf/` 返回 200 但内容是 HTML 落地页。
+ * 它们仍保留为最后兜底，但必须排在所有静态直链与 Unpaywall 结果之后。
+ */
+export declare function isPdfRenderUrl(url: string): boolean;
 /** Europe PMC 的全文 XML 地址；没有 PMCID 时返回 null。 */
 export declare function epmcXmlUrl(paper: Paper): string | null;
 /** Unpaywall 查询（需要联系邮箱，遵守其 polite pool）。 */

package/lib/search/oa.js

@@ -13,6 +13,9 @@ export function pdfCandidates(paper) {
     const candidates = new Set();
     if (paper.pdfUrl !== '')
         candidates.add(paper.pdfUrl);
+    const publisher = publisherPdfUrl(paper.doi);
+    if (publisher !== null)
+        candidates.add(publisher);
     const pmcid = normalizePmcid(paper.ids.pmcid);
     if (pmcid !== '') {
         candidates.add(`${EPMC_ARTICLE}/${pmcid}?pdf=render`);
@@ -22,6 +25,44 @@ export function pdfCandidates(paper) {
         candidates.add(`${ARXIV_PDF}/${paper.ids.arxivId}`);
     return [...candidates];
 }
+/**
+ * 仓储的 PDF 渲染页：浏览器能打开，后台请求却普遍被拦截。
+ *
+ * 实测 `europepmc.org/articles/...?pdf=render` 返回 403 Cloudflare 页、
+ * `ncbi.nlm.nih.gov/pmc/articles/.../pdf/` 返回 200 但内容是 HTML 落地页。
+ * 它们仍保留为最后兜底，但必须排在所有静态直链与 Unpaywall 结果之后。
+ */
+export function isPdfRenderUrl(url) {
+    return url.startsWith(`${EPMC_ARTICLE}/`) || url.startsWith(`${PMC_ARTICLE}/`);
+}
+/**
+ * 部分开放获取出版商的固定 PDF 地址规则。
+ *
+ * Europe PMC / PMC 的渲染页会对后台请求启用 Cloudflare 人机验证（浏览器能打开、
+ * Host 下载却拿到 HTML），因此优先补一条出版商原生 PDF 地址。
+ */
+function publisherPdfUrl(doi) {
+    const value = doi.trim();
+    if (value === '')
+        return null;
+    // BMC / SpringerOpen：https://link.springer.com/content/pdf/<doi>.pdf
+    if (value.startsWith('10.1186/') || value.startsWith('10.1007/')) {
+        return `https://link.springer.com/content/pdf/${encodeURI(value)}.pdf`;
+    }
+    // Frontiers：https://www.frontiersin.org/articles/<doi>/pdf
+    if (value.startsWith('10.3389/')) {
+        return `https://www.frontiersin.org/articles/${encodeURI(value)}/pdf`;
+    }
+    // PLOS ONE
+    if (value.startsWith('10.1371/journal.pone.')) {
+        return `https://journals.plos.org/plosone/article/file?id=${encodeURI(value)}&type=printable`;
+    }
+    // Nature 系列（开放获取文章可下载，订阅文章会落到 HTML 页并继续尝试其它候选）
+    if (value.startsWith('10.1038/')) {
+        return `https://www.nature.com/articles/${encodeURI(value.slice('10.1038/'.length))}.pdf`;
+    }
+    return null;
+}
 /** Europe PMC 的全文 XML 地址；没有 PMCID 时返回 null。 */
 export function epmcXmlUrl(paper) {
     const pmcid = normalizePmcid(paper.ids.pmcid);
@@ -43,13 +84,19 @@ export async function unpaywallPdfCandidates(doi, email, timeoutMs, signal) {
         const body = (await response.json());
         const urls = new Set();
         const best = asRecord(body['best_oa_location']);
-        const bestPdf = asString(best['url_for_pdf']);
-        if (bestPdf !== '')
-            urls.add(bestPdf);
-        for (const raw of asArray(body['oa_locations'])) {
-            const pdf = asString(asRecord(raw)['url_for_pdf']);
-            if (pdf !== '')
+        const locations = [best, ...asArray(body['oa_locations']).map(asRecord)];
+        for (const location of locations) {
+            const pdf = asString(location['url_for_pdf']);
+            if (pdf !== '') {
                 urls.add(pdf);
+                continue;
+            }
+            // 少数仓储只给 `url`，且本身就是 PDF 直链；只收明显是 PDF 的地址，
+            // 避免把落地页塞进候选后又被判成「返回内容不是 PDF」。
+            const landing = asString(location['url']);
+            if (/\.pdf(?:[?#]|$)/iu.test(landing) || /\/pdf\/(?:[?#]|$)/iu.test(landing)) {
+                urls.add(landing);
+            }
         }
         return [...urls];
     }