dsh-plugin-zotero 0.1.7 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -21,7 +21,7 @@
21
21
  - **整理文库**:新建、重命名、移动、删除分类,批量把条目加入或移出分类。你说一句「把这几篇归到『待读』里」,它就照做。
22
22
  - **帮你入库**:把本地下载好的论文、PDF 交给 DSH 导入 Zotero;也可以让它读完外文文献后,把译文作为附件挂回条目。
23
23
  - **带进对话**:右侧面板单条目引用、全文划词摘录或整分类引用,一键写进当前会话草稿(不自动发送),你再接着说要求。
24
- - **安全可控**:浏览面板严格只读;模型能用的每一项工具都能单独开关,想彻底只读就把写操作关掉。
24
+ - **安全可控**:浏览面板严格只读;模型能用的每一项工具都能单独开关,想彻底只读就把写操作关掉;写操作优先走集成 MCP,它在 Zotero 进程内直接执行,不触发本地 API 的授权弹窗。
25
25
 
26
26
  面板分三块:顶部状态栏显示连接状态并提供刷新;左侧分类树按分类浏览与搜索;右侧详情区展示正文与「参考文献 / 笔记 / 标注 / 附件」标签页。
27
27
 
@@ -234,11 +234,13 @@ dsh --profile demo # 启动
234
234
 
235
235
  ### 模型侧 MCP 与权限边界
236
236
 
237
- 模型侧工具由**插件自己**桥接:[src/host/mcp-bridge.ts](src/host/mcp-bridge.ts) 直连本机 Zotero 集成 MCP(本机实测 `zotero-integrated-mcp v1.1.0`,暴露 20 个工具),按配置里的 `disabledMcpTools` 过滤后以 `mcp__zotero__*` 注册给模型。[cordis.patch.yml](cordis.patch.yml) **不再**插入 `@deepseek-ai/dsh-mcp-client` —— 它不支持按工具开关,且同 `serverName` 会与自注册工具重名冲突。
237
+ 模型侧工具由**插件自己**桥接:[src/host/mcp-bridge.ts](src/host/mcp-bridge.ts) 直连本机 Zotero 集成 MCP(本机实测暴露 25 个工具),按配置里的 `disabledMcpTools` 过滤后以 `mcp__zotero__*` 注册给模型。[cordis.patch.yml](cordis.patch.yml) **不再**插入 `@deepseek-ai/dsh-mcp-client` —— 它不支持按工具开关,且同 `serverName` 会与自注册工具重名冲突。
238
238
 
239
239
  ⚠️ 前提是 [Zotero 里已装好集成 MCP 插件](#1-安装-zotero-mcp-插件)(或改用其他 MCP 插件并在配置卡填对 `mcpUrl`),并且开启了「允许写操作」。插件未安装或服务未起时,模型侧工具全部不可用;插件装了但没开写操作时,读类工具正常,`create_collection` 等写工具会被插件拒绝(返回「写操作已禁用」),表现为让模型帮忙新建分类直接报错——此时到 MCP 插件设置里打开写操作并重试即可,无需重启 dsh。
240
240
 
241
- ⚠️ 面板只读,**但模型侧工具不是**:20 个工具中含 5 个改变文库结构的写工具(`create_collection` / `update_collection` / `delete_collection` / `add_items_to_collection` / `remove_items_from_collection`)。想收紧为纯只读,直接在插件页配置卡的「MCP 工具」里关掉它们并保存即可;面板功能不受影响。
241
+ ⚠️ 面板只读,**但模型侧工具不是**:25 个工具中含 10 个写工具(`write_item` / `write_note` / `write_tag` / `write_metadata` / `add_by_identifier` / `create_collection` / `update_collection` / `delete_collection` / `add_items_to_collection` / `remove_items_from_collection`)。想收紧为纯只读,直接在插件页配置卡的「MCP 工具」里关掉它们并保存即可;面板功能不受影响。
242
+
243
+ **写操作为什么优先走 MCP**:这些工具在 Zotero 进程内直接改库,不经过本地 API,因此**不会触发 Zotero 的「本地 API 授权」弹窗**。反过来,若让模型用 shell/curl 直接打 `127.0.0.1:23119` 的写接口,就必须先用 `POST /api/local/authorize` 换 key —— 该端点每次调用都会弹一次授权框,用户点「允许」拿到的 key 还是一次性的(首个写请求即被 Zotero 删除),这就是「每写一次就要点一次允许」的根源。为此插件在 [mcp-bridge.ts](src/host/mcp-bridge.ts) 里给所有写工具的描述统一注入了「首选写通道」引导语;「导入本地文件并挂到某条目下」用 `write_item` 的 `action: "import"` + `filePath` + `parentItemKey`,一条工具调用即可。
242
244
 
243
245
  ## 相关文档
244
246
 
package/client/client.js CHANGED
@@ -75,7 +75,8 @@ const dicts = {
75
75
  "detail.annotationNotAnchoredNoFulltext": "该附件没有全文索引,无法定位",
76
76
  "detail.fulltext": "全文",
77
77
  "detail.noteBody": "笔记正文",
78
- "detail.noFulltext": "该附件没有可用的全文索引",
78
+ "detail.noFulltext": "该条目的附件都没有全文索引;可在 Zotero 中右键附件,选择「重新索引条目」",
79
+ "detail.fulltextFallback": "首选附件没有全文索引,已显示同条目其他附件的全文",
79
80
  "detail.fulltextTruncated": "(已按长度截断)",
80
81
  "detail.collectionSummary": "分类:{name}",
81
82
  "detail.collectionCount": "共 {n} 条条目",
@@ -198,7 +199,8 @@ const dicts = {
198
199
  "detail.annotationNotAnchoredNoFulltext": "No full-text index for this attachment, so it cannot be located",
199
200
  "detail.fulltext": "Full text",
200
201
  "detail.noteBody": "Note",
201
- "detail.noFulltext": "No full-text index available for this attachment",
202
+ "detail.noFulltext": "None of this item’s attachments have a full-text index. Right-click the attachment in Zotero and choose “Reindex Item”.",
203
+ "detail.fulltextFallback": "The preferred attachment has no full-text index; showing another attachment from this item",
202
204
  "detail.fulltextTruncated": "(truncated by length)",
203
205
  "detail.collectionSummary": "Collection: {name}",
204
206
  "detail.collectionCount": "{n} items",
@@ -2633,82 +2635,93 @@ function ItemDetail({ t, detail, onInsertItem, onInsertExcerpt, onInsertAnnotati
2633
2635
  flexDirection: "column",
2634
2636
  padding: "2px 14px 14px"
2635
2637
  },
2636
- children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
2637
- style: {
2638
- display: "flex",
2639
- alignItems: "center",
2640
- gap: 6,
2641
- marginBottom: 6
2642
- },
2643
- children: [
2644
- /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("h3", {
2645
- style: {
2646
- ...sectionTitleStyle,
2647
- margin: 0
2648
- },
2649
- children: [t(selfNote !== null ? "detail.noteBody" : "detail.fulltext"), bodyKey !== "" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
2638
+ children: [
2639
+ /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
2640
+ style: {
2641
+ display: "flex",
2642
+ alignItems: "center",
2643
+ gap: 6,
2644
+ marginBottom: 6
2645
+ },
2646
+ children: [
2647
+ /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("h3", {
2650
2648
  style: {
2651
- opacity: .55,
2652
- fontWeight: 400,
2653
- marginLeft: 8
2649
+ ...sectionTitleStyle,
2650
+ margin: 0
2654
2651
  },
2655
- children: bodyKey
2656
- })]
2657
- }),
2658
- /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { style: { flex: 1 } }),
2659
- selfNote !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
2660
- variant: "outline",
2661
- size: "sm",
2662
- onClick: () => onInsertNote(selfNote),
2663
- title: t("action.insertToChat"),
2664
- style: insertButtonStyle,
2665
- children: t("action.insertItemShort")
2666
- })
2667
- ]
2668
- }), !hasBody ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
2669
- style: {
2670
- margin: 0,
2671
- opacity: .6
2672
- },
2673
- children: t("detail.noFulltext")
2674
- }) : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
2675
- ref: boxRef,
2676
- onMouseUp: handleMouseUp,
2677
- style: selfNote === null ? textBodyStyle : noteBodyStyle,
2678
- children: [selfNote !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
2679
- className: "dsh-zotero-note",
2680
- dangerouslySetInnerHTML: { __html: selfNote.html }
2681
- }), selfNote.truncated && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
2682
- style: truncatedHintStyle,
2683
- children: t("detail.noteTruncated")
2684
- })] }) : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(AnnotatedText, { segments }), fulltext?.truncated === true && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
2685
- style: truncatedHintStyle,
2686
- children: t("detail.fulltextTruncated")
2687
- })] }), selection !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
2688
- type: "button",
2689
- onMouseDown: (event) => event.preventDefault(),
2690
- onClick: () => {
2691
- onInsertExcerpt(selection.text);
2692
- window.getSelection()?.removeAllRanges();
2693
- setSelection(null);
2652
+ children: [t(selfNote !== null ? "detail.noteBody" : "detail.fulltext"), bodyKey !== "" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
2653
+ style: {
2654
+ opacity: .55,
2655
+ fontWeight: 400,
2656
+ marginLeft: 8
2657
+ },
2658
+ children: bodyKey
2659
+ })]
2660
+ }),
2661
+ /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", { style: { flex: 1 } }),
2662
+ selfNote !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
2663
+ variant: "outline",
2664
+ size: "sm",
2665
+ onClick: () => onInsertNote(selfNote),
2666
+ title: t("action.insertToChat"),
2667
+ style: insertButtonStyle,
2668
+ children: t("action.insertItemShort")
2669
+ })
2670
+ ]
2671
+ }),
2672
+ fulltext?.fallback === true && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
2673
+ style: {
2674
+ margin: "0 0 6px",
2675
+ opacity: .6,
2676
+ fontSize: 12
2694
2677
  },
2678
+ children: t("detail.fulltextFallback")
2679
+ }),
2680
+ !hasBody ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
2695
2681
  style: {
2696
- position: "absolute",
2697
- left: selection.x,
2698
- top: selection.y,
2699
- transform: "translate(-50%, -130%)",
2700
- padding: "3px 8px",
2701
- fontSize: 12,
2702
- borderRadius: 6,
2703
- border: "1px solid rgba(127,127,127,0.35)",
2704
- background: "rgba(40,40,40,0.92)",
2705
- color: "#fff",
2706
- cursor: "pointer",
2707
- zIndex: 5
2682
+ margin: 0,
2683
+ opacity: .6
2708
2684
  },
2709
- children: t("action.insertExcerpt")
2710
- })]
2711
- })]
2685
+ children: t("detail.noFulltext")
2686
+ }) : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
2687
+ ref: boxRef,
2688
+ onMouseUp: handleMouseUp,
2689
+ style: selfNote === null ? textBodyStyle : noteBodyStyle,
2690
+ children: [selfNote !== null ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
2691
+ className: "dsh-zotero-note",
2692
+ dangerouslySetInnerHTML: { __html: selfNote.html }
2693
+ }), selfNote.truncated && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
2694
+ style: truncatedHintStyle,
2695
+ children: t("detail.noteTruncated")
2696
+ })] }) : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(AnnotatedText, { segments }), fulltext?.truncated === true && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
2697
+ style: truncatedHintStyle,
2698
+ children: t("detail.fulltextTruncated")
2699
+ })] }), selection !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
2700
+ type: "button",
2701
+ onMouseDown: (event) => event.preventDefault(),
2702
+ onClick: () => {
2703
+ onInsertExcerpt(selection.text);
2704
+ window.getSelection()?.removeAllRanges();
2705
+ setSelection(null);
2706
+ },
2707
+ style: {
2708
+ position: "absolute",
2709
+ left: selection.x,
2710
+ top: selection.y,
2711
+ transform: "translate(-50%, -130%)",
2712
+ padding: "3px 8px",
2713
+ fontSize: 12,
2714
+ borderRadius: 6,
2715
+ border: "1px solid rgba(127,127,127,0.35)",
2716
+ background: "rgba(40,40,40,0.92)",
2717
+ color: "#fff",
2718
+ cursor: "pointer",
2719
+ zIndex: 5
2720
+ },
2721
+ children: t("action.insertExcerpt")
2722
+ })]
2723
+ })
2724
+ ]
2712
2725
  })]
2713
2726
  }),
2714
2727
  hasBottom && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
@@ -32,11 +32,53 @@ function blocksToText(content) {
32
32
  })
33
33
  .join('\n');
34
34
  }
35
+ /**
36
+ * 写工具判定:集成 MCP 里所有会改库的工具名都以这些动词开头
37
+ * (`write_item` / `create_collection` / `add_by_identifier` / `remove_items_from_collection` …)。
38
+ */
39
+ const WRITE_TOOL_RE = /^(write|add|create|update|delete|remove)_/i;
40
+ /** 破坏性写工具:删除/移除类,需要额外的确认提示。 */
41
+ const DESTRUCTIVE_TOOL_RE = /^(delete|remove)_/i;
42
+ /**
43
+ * 注入到写工具描述前面的引导语。
44
+ *
45
+ * 背景:Zotero 的本地 API(23119)写接口必须先用 `POST /api/local/authorize`
46
+ * 换一个 key,而该端点**每次调用都会弹授权框**、且不像应用名复用;模型若绕开
47
+ * MCP 手写 curl,就会每次写都让用户点一次「允许」。集成 MCP 的写工具在 Zotero
48
+ * 进程内直接改库,完全不触发这套授权,因此这里明确把 MCP 标成首选通道。
49
+ *
50
+ * 注意措辞是「优先」而不是「禁止」:集成 MCP 某些场景确实可能失败,必须给模型
51
+ * 留下降级空间,否则它会在报错后继续硬试或改用更糟的方式。
52
+ */
53
+ const WRITE_PREFIX = '[首选写通道] 本工具在 Zotero 进程内执行,不会触发本地 API 授权弹窗。写 Zotero 优先用它。' +
54
+ '仅当本工具不可用或调用失败时再考虑其他方式;不要直接用 shell/curl 访问 http://127.0.0.1:23119,' +
55
+ '那会每次都弹出「本地 API 授权」框让用户点允许。';
56
+ /** 针对「导入本地文件挂到条目下」这一高频场景,直接点明参数组合,省得模型去猜。 */
57
+ const WRITE_ITEM_HINT = '「导入 PDF/文件并挂到某个条目下」用本工具:action=import、filePath=<文件绝对路径>、parentItemKey=<目标条目 key>,title 可选。';
58
+ /** 按标识符入库优先走 Zotero 自带解析器,元数据比模型手填准确。 */
59
+ const IDENTIFIER_HINT = '「按 DOI/arXiv/ISBN/PMID 入库」优先用本工具,它调用 Zotero 自带的元数据解析器,比手填字段准确。';
60
+ const DESTRUCTIVE_HINT = '[破坏性写操作] 执行前必须先与用户确认要操作的具体条目/分类,不要凭推断批量删除或移除。';
61
+ /** 在不改动上游对象的前提下,给写工具的描述拼上引导语。 */
62
+ function descriptionFor(tool) {
63
+ const parts = [];
64
+ if (DESTRUCTIVE_TOOL_RE.test(tool.name))
65
+ parts.push(DESTRUCTIVE_HINT);
66
+ if (WRITE_TOOL_RE.test(tool.name))
67
+ parts.push(WRITE_PREFIX);
68
+ if (tool.name === 'write_item')
69
+ parts.push(WRITE_ITEM_HINT);
70
+ if (tool.name === 'add_by_identifier')
71
+ parts.push(IDENTIFIER_HINT);
72
+ const base = tool.description ?? '';
73
+ if (parts.length === 0)
74
+ return base;
75
+ return `${parts.join('\n\n')}\n\n${base}`;
76
+ }
35
77
  /** 由 MCP 工具造一条 dsh 工具定义(参数直接沿用上游 JSON Schema)。 */
36
78
  function definitionFor(tool) {
37
79
  return {
38
80
  name: publicName(tool.name),
39
- description: tool.description,
81
+ description: descriptionFor(tool),
40
82
  parameters: tool.parameters,
41
83
  output: {
42
84
  schema: {
@@ -450,8 +450,24 @@ export async function getItemFulltext(attachmentKey) {
450
450
  attachmentKey,
451
451
  content: truncated ? content.slice(0, maxBytes) : content,
452
452
  truncated,
453
+ fallback: false,
453
454
  };
454
455
  }
456
+ /**
457
+ * 依次尝试候选附件的全文,返回第一份可用的。
458
+ *
459
+ * 条目常同时挂原文与中文译本:译本若尚未建索引(`/fulltext` 404),
460
+ * 不能直接判定整条无全文,应回退到原文等其他附件。
461
+ */
462
+ async function getFirstFulltext(candidates) {
463
+ const preferredKey = candidates[0]?.key ?? '';
464
+ for (const attachment of candidates) {
465
+ const fulltext = await getItemFulltext(attachment.key);
466
+ if (fulltext !== null)
467
+ return { ...fulltext, fallback: attachment.key !== preferredKey };
468
+ }
469
+ return null;
470
+ }
455
471
  /** 单条条目的 CSL HTML(`format=bib`);失败返回 null。 */
456
472
  export async function getItemBib(key, style) {
457
473
  try {
@@ -478,11 +494,15 @@ export async function getItemDetail(key, style) {
478
494
  // 笔记是子条目(itemType=note);条目本身就是笔记时(独立笔记),正文即自身。
479
495
  const childNotes = children.filter((c) => c.data?.itemType === 'note');
480
496
  const notes = (itemType === 'note' ? [raw] : childNotes).map(toNote);
481
- const readable = isAttachment
482
- ? raw
483
- : childAttachments.find((c) => c.data?.contentType === 'application/pdf') ?? childAttachments[0];
497
+ // 候选顺序:PDF 优先,其余附件随后;逐份尝试直到拿到全文。
498
+ const candidates = isAttachment
499
+ ? [raw]
500
+ : [
501
+ ...childAttachments.filter((c) => c.data?.contentType === 'application/pdf'),
502
+ ...childAttachments.filter((c) => c.data?.contentType !== 'application/pdf'),
503
+ ];
484
504
  const [fulltext, bib] = await Promise.all([
485
- readable ? getItemFulltext(readable.key) : Promise.resolve(null),
505
+ getFirstFulltext(candidates),
486
506
  getItemBib(key, style),
487
507
  ]);
488
508
  // 展示顺序:当前附件的标注排前,同附件内按 PDF 位置(annotationSortIndex 零填充,可字典序比较)。
@@ -105,6 +105,8 @@ export interface ZoteroFulltext {
105
105
  attachmentKey: string;
106
106
  content: string;
107
107
  truncated: boolean;
108
+ /** 首选附件没有全文索引,正文取自同条目的其他附件。 */
109
+ fallback: boolean;
108
110
  }
109
111
  /** 探活结果。 */
110
112
  export interface ZoteroHealth {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-plugin-zotero",
3
- "version": "0.1.7",
3
+ "version": "0.1.8",
4
4
  "description": "Install this plugin and DSH can operate your Zotero for you: search the library, read PDF full text, summarize highlights and notes, organize collections by topic, import your downloaded papers, and attach a translated version back to an item. The right sidebar also gains a Zotero library panel that brings an item, an excerpt or a whole collection into the conversation with one click.",
5
5
  "keywords": [
6
6
  "dsh",
@@ -47,8 +47,8 @@
47
47
  },
48
48
  "devDependencies": {
49
49
  "@deepseek-ai/cordis": "^4.0.5",
50
- "@deepseek-ai/dsh": "0.2.1-rc.3",
51
- "@deepseek-ai/dsh-tools": "0.2.1-rc.3",
50
+ "@deepseek-ai/dsh": "0.2.1-rc.5",
51
+ "@deepseek-ai/dsh-tools": "0.2.1-rc.5",
52
52
  "@deepseek-ai/schemastery": "3.18.5",
53
53
  "@types/node": "^24.19.2",
54
54
  "@types/react": "~18.3.1",