dsh-plugin-zotero 0.1.3 → 0.1.4

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.
Files changed (3) hide show
  1. package/README.md +23 -12
  2. package/client/client.js +67 -48
  3. package/package.json +9 -9
package/README.md CHANGED
@@ -1,6 +1,10 @@
1
1
  # dsh-plugin-zotero
2
2
 
3
- 基于 [cordis](https://github.com/deepseek-ai/cordis) 的 DSH 插件,把本机 Zotero 文献库接进 DSH。分两半,职责不重叠、互不依赖:
3
+ **把 Zotero 和 DSH 连起来。**
4
+
5
+ 装好这个插件,大模型就能直接查看、检索和读取你 Zotero 里的文献、笔记和 PDF 全文;你也可以在 DSH 右侧栏浏览自己的文库,把条目、摘录或整个目录一键带进对话。
6
+
7
+ 不用写代码,也不用记命令。第一次使用前,只需在 Zotero 里完成两项一次性设置(装一个桥接小插件、打开通信开关),步骤见[使用前提](#使用前提)。
4
8
 
5
9
  ## 截图
6
10
 
@@ -8,24 +12,20 @@
8
12
 
9
13
  <sub>上图为 DSH 会话与右侧「Zotero 文献库」面板:上方正文区展示元数据与全文,下方分区 tab 展示参考文献、笔记与附件,点击图片可查看原图。</sub>
10
14
 
11
- 面板分三块:
15
+ 一句话概括它能做什么:
12
16
 
13
- - **顶部状态栏**:显示 Zotero 是否已连接、模型工具是否可用,并提供刷新。
14
- - **左侧分类树**:按 Zotero 分类逐级浏览,支持按标题 / 摘要搜索。
15
- - **右侧详情**:上方正文区展示条目元数据、可折叠摘要与 PDF 全文;下方分区 tab 切换参考文献、笔记、附件;「添加条目引用」把引用写入当前会话草稿。
17
+ - **浏览与检索**:按 Zotero 分类逐级浏览文库,按标题 / 摘要搜索,查看条目的元数据、摘要、参考文献、笔记、附件与 PDF 全文。
18
+ - **带进对话**:单条目引用、全文划词摘录或整目录引用,一键写进当前会话草稿(不自动发送),模型可以接着基于它工作。
19
+ - **交给模型**:让大模型帮你找文献、读全文、整理笔记,必要时按你的要求调整分类;不想让模型改文库,可以逐个关掉写操作。
20
+ - **安全可控**:浏览面板严格只读;模型能做什么可以逐项开关。
16
21
 
17
- | 半边 | 能力 | 通道 |
18
- |---|---|---|
19
- | **人侧面板** | 在 DSH 右侧栏只读浏览 Zotero 文库(分类树 / 搜索 / 条目详情 / 笔记 / PDF 全文),把条目、摘录或整目录引用写进会话草稿 | 插件在宿主 web server 自注册的 `/dsh-zotero/api/*` 路由 |
20
- | **模型侧** | 检索、精读、按需操作文库 | 插件**自持**连接本机 Zotero 集成 MCP,工具以 `mcp__zotero__*` 注册给模型 |
21
-
22
- MCP 没起,面板照常可用;Zotero 没开,模型工具自然也不可用。
22
+ 面板分三块:顶部状态栏显示连接状态并提供刷新;左侧分类树按分类浏览与搜索;右侧详情区展示正文与「参考文献 / 笔记 / 附件」标签页。
23
23
 
24
24
  > 面向使用者的完整说明(入口、交互、toast 与错误对照表)见 [插件使用说明](docs/插件使用说明/dsh-plugin-zotero使用说明.zh.md)。
25
25
 
26
26
  ## 安装
27
27
 
28
- 要求 dsh ≥ 0.2.0-rc.2(`package.json` 的 `engines.dsh` 为 `>=0.2.0-rc.2 <0.3.0-0`)。
28
+ 要求 dsh ≥ 0.2.1-rc.3(`package.json` 的 `engines.dsh` 为 `>=0.2.1-rc.3 <0.3.0-0`)。
29
29
 
30
30
  ```sh
31
31
  # 从 npm(推荐)
@@ -113,6 +113,17 @@ MCP 组下方是 **「MCP 工具」** 区:现场列出集成 MCP 的全部工
113
113
 
114
114
  ## 架构
115
115
 
116
+ 从使用者视角看,插件分两半,职责不重叠、互不依赖:
117
+
118
+ | 半边 | 能力 | 通道 |
119
+ |---|---|---|
120
+ | **人侧面板** | 在 DSH 右侧栏只读浏览 Zotero 文库(分类树 / 搜索 / 条目详情 / 笔记 / PDF 全文),把条目、摘录或整目录引用写进会话草稿 | 插件在宿主 web server 自注册的 `/dsh-zotero/api/*` 路由 |
121
+ | **模型侧** | 检索、精读、按需操作文库 | 插件**自持**连接本机 Zotero 集成 MCP,工具以 `mcp__zotero__*` 注册给模型 |
122
+
123
+ MCP 没起,面板照常可用;Zotero 没开,模型工具自然也不可用。
124
+
125
+ 代码分布:
126
+
116
127
  | 半边 | 代码位置 | 通道 |
117
128
  |---|---|---|
118
129
  | Host | `src/index.ts`、`src/host/`、`src/zotero/` | 把 Zotero 本地 API 包装成只读 HTTP 端点,挂在 DSH 宿主 web server 上 |
package/client/client.js CHANGED
@@ -273,8 +273,12 @@ function fetchCollectionBib(key, style = "apa") {
273
273
  const SEARCH_DEBOUNCE_MS = 250;
274
274
  /** 搜索结果条数上限。 */
275
275
  const SEARCH_LIMIT = 100;
276
+ /** 分类树每个节点一次最多拉取的条目数。 */
277
+ const NODE_LIMIT = 200;
276
278
  /** 提示条停留时长。 */
277
279
  const TOAST_MS = 3e3;
280
+ /** 文库根节点的 id(只存在于客户端,不对应任何 Zotero 分类)。 */
281
+ const TREE_ROOT_ID = "__library__";
278
282
  function initialState() {
279
283
  return {
280
284
  health: null,
@@ -283,6 +287,9 @@ function initialState() {
283
287
  treeError: null,
284
288
  treeLoading: true,
285
289
  loaded: false,
290
+ expanded: /* @__PURE__ */ new Set([TREE_ROOT_ID]),
291
+ nodeItems: {},
292
+ nodeTotals: {},
286
293
  query: "",
287
294
  results: null,
288
295
  selectedItemKey: null,
@@ -299,6 +306,7 @@ function errorMessage(error) {
299
306
  let state = initialState();
300
307
  const listeners = /* @__PURE__ */ new Set();
301
308
  let treeInflight = null;
309
+ const nodeInflight = /* @__PURE__ */ new Set();
302
310
  let searchTimer = null;
303
311
  let toastTimer = null;
304
312
  function patch(next) {
@@ -357,6 +365,53 @@ function loadTree(force = false) {
357
365
  treeInflight = run;
358
366
  return run;
359
367
  }
368
+ /** 按需拉取某节点的条目;已拉取或正在拉取时直接返回。 */
369
+ function loadNodeItems(nodeId, target) {
370
+ if (state.nodeItems[nodeId] !== void 0 || nodeInflight.has(nodeId)) return;
371
+ nodeInflight.add(nodeId);
372
+ fetchItems({
373
+ ...target,
374
+ limit: NODE_LIMIT
375
+ }).then((data) => {
376
+ patch({
377
+ nodeItems: {
378
+ ...state.nodeItems,
379
+ [nodeId]: data.items
380
+ },
381
+ nodeTotals: {
382
+ ...state.nodeTotals,
383
+ [nodeId]: data.total
384
+ }
385
+ });
386
+ }).catch(() => {
387
+ patch({
388
+ nodeItems: {
389
+ ...state.nodeItems,
390
+ [nodeId]: []
391
+ },
392
+ nodeTotals: {
393
+ ...state.nodeTotals,
394
+ [nodeId]: 0
395
+ }
396
+ });
397
+ }).finally(() => {
398
+ nodeInflight.delete(nodeId);
399
+ });
400
+ }
401
+ /** 三角箭头:只开合节点,展开时按需拉取条目(根节点没有条目,不传 target)。 */
402
+ function toggleTreeNode(nodeId, target) {
403
+ const willOpen = !state.expanded.has(nodeId);
404
+ const expanded = new Set(state.expanded);
405
+ if (willOpen) expanded.add(nodeId);
406
+ else expanded.delete(nodeId);
407
+ patch({ expanded });
408
+ if (willOpen && target !== void 0) loadNodeItems(nodeId, target);
409
+ }
410
+ /** 选中分类时调用:确保节点展开且条目已拉取。 */
411
+ function expandTreeNode(nodeId, target) {
412
+ if (!state.expanded.has(nodeId)) patch({ expanded: new Set(state.expanded).add(nodeId) });
413
+ loadNodeItems(nodeId, target);
414
+ }
360
415
  /** 更新搜索词并按防抖取数;清空时回到分类树。 */
361
416
  function setQuery(next) {
362
417
  patch({ query: next });
@@ -410,6 +465,7 @@ function resetPaneStore() {
410
465
  searchTimer = null;
411
466
  toastTimer = null;
412
467
  treeInflight = null;
468
+ nodeInflight.clear();
413
469
  state = initialState();
414
470
  for (const listener of listeners) listener();
415
471
  }
@@ -738,10 +794,9 @@ function ZoteroCard(props) {
738
794
  * - 「我的文库」根节点**不再平铺全库条目**(这些条目本就挂在各分类下,平铺会造成重复);
739
795
  * 其下额外挂三个虚拟分类:我的出版物 / 未分类条目 / 回收站,与 Zotero 左侧栏一致。
740
796
  * - 分类 / 条目右键 → 「添加到会话」。
797
+ * - 展开集合与各节点条目都放在 {@link paneStore}:右侧栏切 tab 时面板正文会被卸载
798
+ * 重挂,局部 state 会丢,只有模块级 store 能让树保持原样。
741
799
  */
742
- /** 每个节点一次最多拉取的条目数。 */
743
- const NODE_LIMIT = 200;
744
- const ROOT_NODE = "__library__";
745
800
  /** 每层缩进量(px)。 */
746
801
  const INDENT = 14;
747
802
  /** 树左起始留白(px)。 */
@@ -1075,50 +1130,14 @@ function VirtualRows({ ctx, node, depth }) {
1075
1130
  }
1076
1131
  function CollectionTree(props) {
1077
1132
  const { t, collections, selectedItemKey, selectedCollectionKey, onSelectItem, onSelectCollection, onInsertItem, onInsertCollection } = props;
1078
- /** 默认展开根节点,进面板就能看到顶层分类(与 Zotero 一致)。 */
1079
- const [expanded, setExpanded] = (0, react.useState)(() => /* @__PURE__ */ new Set([ROOT_NODE]));
1080
- const [itemsByNode, setItemsByNode] = (0, react.useState)({});
1081
- const [totalsByNode, setTotalsByNode] = (0, react.useState)({});
1082
- async function load(nodeId, opts = {}) {
1083
- if (itemsByNode[nodeId] !== void 0) return;
1084
- try {
1085
- const data = await fetchItems({
1086
- ...opts,
1087
- limit: NODE_LIMIT
1088
- });
1089
- setItemsByNode((prev) => ({
1090
- ...prev,
1091
- [nodeId]: data.items
1092
- }));
1093
- setTotalsByNode((prev) => ({
1094
- ...prev,
1095
- [nodeId]: data.total
1096
- }));
1097
- } catch {
1098
- setItemsByNode((prev) => ({
1099
- ...prev,
1100
- [nodeId]: []
1101
- }));
1102
- setTotalsByNode((prev) => ({
1103
- ...prev,
1104
- [nodeId]: 0
1105
- }));
1106
- }
1107
- }
1133
+ /** 展开集合与各节点条目都在 store 里(默认展开根节点),重挂面板后原样恢复。 */
1134
+ const { expanded, nodeItems, nodeTotals } = usePaneState();
1108
1135
  /** 按需拉取:条目一律由 toggle / select 触发,根节点不再预取全库条目。 */
1109
1136
  function open(nodeId, collection) {
1110
- setExpanded((prev) => prev.has(nodeId) ? prev : new Set(prev).add(nodeId));
1111
- load(nodeId, loadOpts(collection));
1137
+ expandTreeNode(nodeId, loadOpts(collection));
1112
1138
  }
1113
1139
  function toggle(nodeId, collection) {
1114
- const willOpen = !expanded.has(nodeId);
1115
- setExpanded((prev) => {
1116
- const next = new Set(prev);
1117
- if (willOpen) next.add(nodeId);
1118
- else next.delete(nodeId);
1119
- return next;
1120
- });
1121
- if (willOpen && collection !== void 0) load(nodeId, loadOpts(collection));
1140
+ toggleTreeNode(nodeId, collection === void 0 ? void 0 : loadOpts(collection));
1122
1141
  }
1123
1142
  function select(collection) {
1124
1143
  onSelectCollection(collection);
@@ -1127,8 +1146,8 @@ function CollectionTree(props) {
1127
1146
  const ctx = {
1128
1147
  t,
1129
1148
  expanded,
1130
- itemsByNode,
1131
- totalsByNode,
1149
+ itemsByNode: nodeItems,
1150
+ totalsByNode: nodeTotals,
1132
1151
  selectedItemKey,
1133
1152
  selectedCollectionKey,
1134
1153
  toggle,
@@ -1137,7 +1156,7 @@ function CollectionTree(props) {
1137
1156
  onInsertItem,
1138
1157
  onInsertCollection
1139
1158
  };
1140
- const rootOpen = expanded.has(ROOT_NODE);
1159
+ const rootOpen = expanded.has(TREE_ROOT_ID);
1141
1160
  return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
1142
1161
  style: {
1143
1162
  padding: "8px 6px",
@@ -1145,7 +1164,7 @@ function CollectionTree(props) {
1145
1164
  flexDirection: "column"
1146
1165
  },
1147
1166
  children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
1148
- onClick: () => toggle(ROOT_NODE),
1167
+ onClick: () => toggle(TREE_ROOT_ID),
1149
1168
  style: {
1150
1169
  ...rowStyle,
1151
1170
  ...rowIndent(0)
@@ -1153,7 +1172,7 @@ function CollectionTree(props) {
1153
1172
  children: [
1154
1173
  /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Chevron, {
1155
1174
  open: rootOpen,
1156
- onToggle: () => toggle(ROOT_NODE)
1175
+ onToggle: () => toggle(TREE_ROOT_ID)
1157
1176
  }),
1158
1177
  /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
1159
1178
  style: iconBox,
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "dsh-plugin-zotero",
3
- "version": "0.1.3",
4
- "description": "Bring your local Zotero library into DeepSeek Harness: a read-only sidebar panel for browsing, searching and inserting citations into conversation drafts, plus a self-hosted integration-MCP bridge that registers Zotero tools to the model with per-tool toggles.",
3
+ "version": "0.1.4",
4
+ "description": "Connect the Zotero library on your computer to DSH: browse and search your own papers in the right sidebar, read metadata, notes and PDF full text, and bring a citation, an excerpt or a whole collection into the conversation with one click, so the model can answer from your own literature.",
5
5
  "keywords": [
6
6
  "dsh",
7
7
  "deepseek",
@@ -33,17 +33,17 @@
33
33
  "cordis.patch.yml"
34
34
  ],
35
35
  "engines": {
36
- "dsh": ">=0.2.0-rc.2 <0.3.0-0"
36
+ "dsh": ">=0.2.1-rc.3 <0.3.0-0"
37
37
  },
38
38
  "peerDependencies": {
39
- "@deepseek-ai/cordis": "^4.0.1",
40
- "@deepseek-ai/schemastery": "^3.18.4"
39
+ "@deepseek-ai/cordis": "^4.0.5",
40
+ "@deepseek-ai/schemastery": "^3.18.5"
41
41
  },
42
42
  "devDependencies": {
43
- "@deepseek-ai/cordis": "^4.0.4",
44
- "@deepseek-ai/dsh": "0.2.0-rc.2",
45
- "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
46
- "@deepseek-ai/schemastery": "3.18.4",
43
+ "@deepseek-ai/cordis": "^4.0.5",
44
+ "@deepseek-ai/dsh": "0.2.1-rc.3",
45
+ "@deepseek-ai/dsh-tools": "0.2.1-rc.3",
46
+ "@deepseek-ai/schemastery": "3.18.5",
47
47
  "@types/node": "^24.19.2",
48
48
  "@types/react": "~18.3.1",
49
49
  "react": "^18.3.1",