dsh-plugin-zotero 0.5.2 → 0.6.1

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
@@ -6,7 +6,7 @@
6
6
 
7
7
  模型侧同样具备完整的检索与整理能力:检索文库、精读 PDF、汇总高亮与笔记、按主题新建分类并归类,也可以把本地下载的论文导入 Zotero,读完外文文献后把译文作为附件回挂到对应条目。凡 Zotero 本地接口与集成 MCP 能提供的操作,均可由模型代劳。
8
8
 
9
- 不用写代码,也不用记命令。第一次使用前,只需在 Zotero 里完成两项一次性设置(装一个桥接小插件、打开通信开关),步骤见[使用前提](#使用前提)。
9
+ 不用写代码,也不用记命令。第一次使用照着[安装与设置](#安装与设置)点 5 步就行(装插件、给 Zotero 装个桥接小插件、打开一个通信开关、确认连上、按需开写权限),全都是一次性的,以后打开 Zotero 和 DSH 直接用。
10
10
 
11
11
  ## 截图
12
12
 
@@ -25,61 +25,169 @@
25
25
  - **整理文库**:新建、重命名、移动、删除分类,批量把条目加入或移出分类。你说一句「把这几篇归到『待读』里」,它就照做。
26
26
  - **帮你入库**:把本地下载好的论文、PDF 交给 DSH 导入 Zotero;也可以让它读完外文文献后,把译文作为附件挂回条目。
27
27
  - **带进对话**:右侧面板单条目引用、列表多选批量引用、阅读页划词摘录与点高亮引用、单标签或多标签引用、整分类引用,一键写进当前会话草稿(不自动发送),你再接着说要求。条目、标签和整分类以「引用胶囊」的形式出现,草稿里一眼看清引了哪几篇,单独删掉某一条也不影响其他内容。
28
- - **安全可控**:写能力默认全关 —— 配置卡里「Zotero 写权限」不开启,面板就是纯只读,模型也看不到任何写工具。开启后写操作优先走集成 MCP(在 Zotero 进程内执行,不触发本地 API 授权弹窗),标注与笔记这两类 MCP 覆盖不到的才走本地 API,需要一次性点「始终允许」授权;模型侧每一项工具都能单独开关。
28
+ - **安全可控**:写能力默认全关 —— 「设置 → Zotero 插件」里的「Zotero 写权限」不开启,面板就是纯只读,模型也看不到任何写工具。开启后写操作优先走集成 MCP(在 Zotero 进程内执行,不触发本地 API 授权弹窗),标注与笔记这两类 MCP 覆盖不到的才走本地 API,需要一次性点「始终允许」授权;模型侧每一项工具都能单独开关。
29
29
 
30
30
  面板布局与 Zotero 本体一致:顶部状态栏显示连接状态并提供刷新;左侧是分类树,树下是可拖高、可折叠的标签面板;右侧列表显示当前范围(分类 / 全库 / 标签筛选后)的条目。分类树与条目列表之间的分隔条可拖动,宽度按本机记住。列表里单击条目选中、`Ctrl` / `Cmd` 点选多选,双击才在右侧栏顶层单开一个标签页看详情。阅读页就开在会话旁边的标签里,边读边摘、边问边改,不必在 Zotero 与 AI 两个窗口之间来回切换。
31
31
 
32
32
  > 面向使用者的完整说明(入口、交互、toast 与错误对照表)见 [插件使用说明](docs/插件使用说明/dsh-plugin-zotero使用说明.zh.md)。
33
33
 
34
- ## 安装
34
+ ## 安装与设置
35
35
 
36
- 要求 dsh ≥ 0.2.1-rc.3(`package.json` 的 `engines.dsh` 为 `>=0.2.1-rc.3 <0.3.0-0`)。
36
+ 第一次使用要走 5 步,**全程点鼠标,不用敲命令、不用写代码**。这 5 步都是一次性的,做完以后每天只要打开 Zotero 和 DSH 就能用。
37
+
38
+ | 步骤 | 在哪做 | 做什么 | 必须吗 |
39
+ |---|---|---|---|
40
+ | [1](#第-1-步在-dsh-里安装本插件) | DSH | 安装本插件 | 必须 |
41
+ | [2](#第-2-步给-zotero-装一个桥接小插件) | Zotero | 装桥接小插件 Zotero MCP Plugin | 想让 AI 动手就必须 |
42
+ | [3](#第-3-步打开-zotero-的本机通信开关) | Zotero | 打开「允许本机其他程序通信」开关 | 必须 |
43
+ | [4](#第-4-步回到-dsh-确认已经连上) | DSH | 到「设置 → Zotero 插件」看一眼 | 必须(只是确认) |
44
+ | [5](#第-5-步可选想让-ai-帮你改文献库) | DSH + Zotero | 打开写权限并授权 | 想改库 / 划高亮才需要 |
45
+
46
+ 开始前请确认两件事:**Zotero 桌面版已装好并且正开着**(本插件读的是你本机 Zotero 里的文献,不是云端);**DSH 桌面版 ≥ 0.2.1-rc.3**。
47
+
48
+ ### 第 1 步:在 DSH 里安装本插件
49
+
50
+ 1. 打开 DSH,进「设置」→ 左侧的「**插件市场**」。
51
+ 2. 如果页面提示「还没有插件索引」,点「**添加索引源**」,把这个地址填进去再点「添加」:`https://awesome-dsh-plugin.com/index.json`。这是社区维护的插件目录,只需加一次。
52
+ 3. 回到「发现」,搜索框里输入 `zotero`,找到 **dsh-plugin-zotero**(作者 peijiping),点开它。
53
+ 4. 点「**安装**」,在弹出的确认框里确认,等安装进度走完。
54
+ 5. 按提示**重启 DSH**。
55
+
56
+ 怎么算装好了:重启后 DSH 右侧栏多出「**Zotero 文献库**」入口,「设置」左侧列表里(「Agent 预设」下面)多出「**Zotero 插件**」一页。看到这两个就对了。
57
+
58
+ <details>
59
+ <summary>习惯用命令行的人可以这样装(可选,效果一样)</summary>
37
60
 
38
61
  ```sh
39
- # 从 npm(推荐)
40
62
  dsh plugin --profile <profile> add dsh-plugin-zotero
41
-
42
- # 或从插件市场安装:dsh 插件页 → 发现 → 添加索引源
43
- # https://awesome-dsh-plugin.com/index.json
44
63
  ```
45
64
 
46
- 包内是预构建产物(`lib/` + `client/client.js`),安装时**不运行构建脚本**,无需 `allowBuilds` 授权。本地源码开发见[方案一:本地路径安装](docs/插件发布/方案一本地路径安装.zh.md)。
65
+ 包内是预构建产物(`lib/` + `client/client.js`),安装时**不运行构建脚本**,无需 `allowBuilds` 授权。要求 dsh ≥ 0.2.1-rc.3(`package.json` 的 `engines.dsh` 为 `>=0.2.1-rc.3 <0.3.0-0`)。本地源码开发见[方案一:本地路径安装](docs/插件发布/方案一本地路径安装.zh.md)。
47
66
 
48
- ## 使用前提
67
+ </details>
49
68
 
50
- 使用本插件前,本机 Zotero 需备好两件事:**集成 MCP 插件**与**本地 API**。
69
+ ### 第 2 步:给 Zotero 装一个桥接小插件
51
70
 
52
- ### 1. 安装 Zotero MCP 插件
71
+ AI 要替你新建分类、导入论文、改条目信息,靠的是 Zotero 端的一个小插件(叫 **Zotero MCP Plugin**)。它装在 Zotero 里,装完不用配置。
53
72
 
54
- 在 Zotero 的插件市场搜索 `mcp`,安装列表第一行、标签为 `ai` / `integration` 的 **Zotero MCP Plugin**(即 `zotero-integrated-mcp`)。装好后无需额外配置,默认监听 `http://127.0.0.1:23120/mcp`。
73
+ 1. 打开 Zotero,菜单「**工具 → 插件**」。
74
+ 2. 在插件市场里搜 `mcp`。
75
+ 3. 安装列表**第一行**、标签是 `ai` / `integration` 的那个 **Zotero MCP Plugin**(包名 `zotero-integrated-mcp`)。
76
+ 4. 装好后不需要额外设置,它默认在 `http://127.0.0.1:23120/mcp` 上待命。
55
77
 
56
78
  [![Zotero 插件市场中安装 Zotero MCP Plugin](docs/images/zotero-mcp-plugin-market.png)](docs/images/zotero-mcp-plugin-market.png)
57
79
 
58
80
  <sub>上图为 Zotero 插件市场,第一行「Zotero MCP Plugin」已安装。</sub>
59
81
 
60
- 如果装的是**其他** MCP 插件,或它的监听地址 / 端口不是 23120,到 dsh「插件」面板展开 `dsh-plugin-zotero` → 「配置 dsh-plugin-zotero」,把 **MCP 设置 → `mcpUrl`** 改成实际端点(如 `http://127.0.0.1:<端口>/mcp`)并保存,即时生效,无需重启。字段说明见[插件页配置项](#插件页配置项)。
82
+ 装完还要**在它的设置里勾选「允许写操作」**,否则 AI 能查能读,但让它新建分类会直接报「写操作已禁用」。
61
83
 
62
- > 没装 MCP 插件不影响右侧面板使用,只是模型侧 `mcp__zotero__*` 工具不可用。
84
+ > 这一步不做也能用右侧面板浏览文献,只是 AI 那边的 Zotero 工具用不了。如果你装的是**别的** MCP 插件、或端口不是 23120,见[第 4 步](#第-4-步回到-dsh-确认已经连上)改地址。
63
85
 
64
- ### 2. 开启 Zotero 本地 API
86
+ ### 第 3 步:打开 Zotero 的本机通信开关
65
87
 
66
- Zotero → 设置 → 高级 → 勾选 **「允许此计算机上的其他应用程序与 Zotero 通信」**(默认端口 23119,仅监听回环)。
88
+ Zotero 默认不允许别的程序读它的文献库。这个开关就是放行同一台电脑上的程序(也就是 DSH)——**数据不出本机**,端口只对本机开放。
89
+
90
+ Zotero → **设置** → **高级** → 勾选「**允许此计算机上的其他应用程序与 Zotero 通信**」。
67
91
 
68
92
  [![在 Zotero 高级设置中允许其他应用与 Zotero 通信](docs/images/zotero-allow-communication.png)](docs/images/zotero-allow-communication.png)
69
93
 
70
94
  <sub>上图为 Zotero「设置 → 高级」中开启本地 API 的开关。</sub>
71
95
 
72
- 验证:
96
+ 没勾选的话,DSH 面板会显示「Zotero 未连接」并提示你回来开这个开关。想自己确认一下,可以在浏览器里打开 `http://127.0.0.1:23119/api/`,看到 `Zotero is running` 就是通了(命令行等价写法:`curl http://127.0.0.1:23119/api/`)。
73
97
 
74
- ```sh
75
- curl http://127.0.0.1:23119/api/ # 期望输出:Zotero is running
76
- ```
98
+ ### 第 4 步:回到 DSH 确认已经连上
99
+
100
+ 打开 DSH 的「**设置**」,点左侧列表里的「**Zotero 插件**」。这一页就是本插件的全部设置,从上到下三块:**Zotero 写权限**、**API 设置**、**MCP 设置**。
101
+
102
+ - 正常情况**一个字都不用改**,默认值就是对的。每一项的含义见[设置项说明](#设置项说明设置--zotero-插件)。
103
+ - 回到会话,打开右侧栏的「Zotero 文献库」:顶部状态栏显示连接状态,左边应该已经列出你在 Zotero 里的分类。看到分类树就说明整条链路通了。
104
+ - 如果 Zotero 里装的 MCP 插件不是第 2 步那个、或者端口不是 23120:把「**MCP 设置 → 集成 MCP 地址**」改成实际地址(形如 `http://127.0.0.1:<端口>/mcp`)。改完自动保存、立即生效,不用重启。
105
+
106
+ ### 第 5 步(可选):想让 AI 帮你改文献库
107
+
108
+ **默认是只读的**:面板只能看和引用,AI 也看不到任何写工具。想在读 PDF 时直接划高亮、写笔记,或者让 AI 帮你整理分类、导入论文,就打开写权限:
109
+
110
+ 1. 「设置 → Zotero 插件」最上面那块「Zotero 写权限」,打开「**允许写入 Zotero**」开关。
111
+ 2. 等一秒左右让它自动保存(页面会闪一下「正在自动保存…」),下面的按钮就可以点了。
112
+ 3. 点「**授权 Zotero 写权限**」。Zotero 会弹出一个确认框,**一定要选「始终允许」**——选「允许」只管一次,第二次写入就又失败了。
113
+ 4. 状态行变成「**已授权(永久有效),重启 DSH 后继续可用**」就完成了。以后重启 DSH、重启 Zotero 都不用再点。
114
+
115
+ [![DSH 设置里的 Zotero 写权限开关与授权按钮](docs/images/zotero-settings-write.png)](docs/images/zotero-settings-write.png)
116
+
117
+ <sub>上图为「设置 → Zotero 插件」顶部的写权限区块:开关已打开、状态显示「已授权(永久有效)」,主按钮已降级为「重新授权」——正常使用的情况下你不需要再点它。旁边的「重新读取」只是重新查一下本机保存的授权状态,写入报错时点它。</sub>
118
+
119
+ 授权凭据存在本机 `~/.dsh/storages/dsh-plugin-zotero/local-api-key.json`(权限 `0600`,不会出现在任何表单里)。要收回权限,在 Zotero 里清除本地 API 授权即可,插件下次写入被拒后会自动删掉本地副本、回到「未授权」。想临时全面止损,把「允许写入 Zotero」关掉就彻底回到只读。
120
+
121
+ > 写入是**直接改你本机的 Zotero 库**,插件不另存副本。删除类操作在面板里要点两次(「删除」→「确认删除」)才真删,而且**不进 Zotero 回收站**,撤销不了。
122
+
123
+ ## 设置项说明(设置 → Zotero 插件)
124
+
125
+ 入口只有一个:DSH 的「**设置**」→ 左侧「**Zotero 插件**」。
126
+
127
+ **没有保存按钮**:任何一项改完、停手约一秒就自动落盘,页面顶部会显示「正在自动保存…」,失败会显示红字提示(再改任意一项就会重试)。所有改动**立即生效,不用重启 DSH**。字段旁出现「已覆盖」表示这一项被你改过、不是默认值,点「恢复默认」即可还原。
128
+
129
+ ### Zotero 写权限
130
+
131
+ 见[第 5 步](#第-5-步可选想让-ai-帮你改文献库)。一句话:**开关管「有没有写入口」,授权按钮管「Zotero 认不认」**,两件事都做完才写得进去。
132
+
133
+ ### API 设置
134
+
135
+ 这块管右侧面板怎么连你本机的 Zotero。**四项默认值适用于绝大多数人,不用动。**
77
136
 
78
- 未勾选时读端点返回 403,面板显示「Zotero 未连接」并提示启用步骤。
137
+ [![DSH 设置中的 API 设置四项](docs/images/zotero-settings-api.png)](docs/images/zotero-settings-api.png)
138
+
139
+ <sub>上图为「API 设置」区块,显示的是四项的默认值。</sub>
140
+
141
+ | 界面上的名字 | 默认值 | 说人话 | 什么时候才需要改 |
142
+ |---|---|---|---|
143
+ | **Zotero 地址** | `http://127.0.0.1:23119` | 本机 Zotero 的门牌号,面板所有数据都从这里取 | 你在 Zotero 里改过本地 API 端口 |
144
+ | **请求超时(毫秒)** | `5000` | 等 Zotero 回话最多等 5 秒,超了就报错 | 库特别大、经常提示超时,可以调到 10000 |
145
+ | **全文上限(字节)** | `204800` | 一篇附件的纯文本最多给这么多(约 200 KB,中文约 6~7 万字),超出部分截掉 | 想让 AI 一次读到更长的全文,可以调大(更费 token) |
146
+ | **默认条目数** | `50` | 面板列表一次先拉 50 条,往下点「加载更多」再续 | 想一屏看到更多条目 |
147
+
148
+ <sub>对应配置字段名(写配置文件时才用得到):`zoteroBaseUrl`、`requestTimeoutMs`、`fulltextMaxBytes`、`defaultLimit`。</sub>
149
+
150
+ ### MCP 设置
151
+
152
+ 这块管 AI 那边怎么连 Zotero 的桥接小插件。
153
+
154
+ | 界面上的名字 | 默认值 | 说人话 | 什么时候才需要改 |
155
+ |---|---|---|---|
156
+ | **集成 MCP 地址** | `http://127.0.0.1:23120/mcp` | 第 2 步装的那个小插件的接头地址 | 换了别的 MCP 插件,或它的端口不是 23120 |
157
+ | **MCP 探活超时(毫秒)** | `800` | 每次判断「AI 工具能不能用」时,最多等 0.8 秒 | 机器很慢、状态栏老是误报「模型工具不可用」 |
158
+
159
+ <sub>对应配置字段名:`mcpUrl`、`mcpProbeTimeoutMs`。</sub>
160
+
161
+ ### MCP 工具(AI 能力逐项开关)
162
+
163
+ 再往下是「**MCP 工具**」清单:现场列出桥接小插件提供的全部工具(本机实测 25 个),每行右边一个开关,顶部写着「共 N 个工具,已禁用 M 个」。
164
+
165
+ - **关掉某一项**,AI 就再也用不了那个能力(等于从 AI 的工具表里摘掉),比如你不想让 AI 删分类,就把 `delete_collection` 关掉。
166
+ - 「**重新读取**」重新拉一次清单;显示「读取工具列表失败」通常是 Zotero 没开或小插件没装。
167
+ - 清单里名字带 `write_` / `create_` / `update_` / `delete_` / `add_` / `remove_` 的是会改库的工具,其余是只读的。
168
+
169
+ [![DSH 设置中的 MCP 设置与 MCP 工具开关清单](docs/images/zotero-settings-mcp.png)](docs/images/zotero-settings-mcp.png)
170
+
171
+ <sub>上图为「MCP 设置」区块与下方的「MCP 工具」清单:共 25 个工具、已禁用 0 个,每行右侧的开关单独控制 AI 能不能使用该工具。</sub>
172
+
173
+ ## 常见问题
174
+
175
+ | 你看到的 | 大概率原因 | 怎么办 |
176
+ |---|---|---|
177
+ | 面板显示「Zotero 未连接」 | Zotero 没开,或第 3 步的通信开关没勾 | 打开 Zotero,勾上「允许此计算机上的其他应用程序与 Zotero 通信」,回面板点刷新 |
178
+ | 状态栏「模型工具不可用」,或工具清单读取失败 | 第 2 步的小插件没装 / 端口不是 23120 | 装 Zotero MCP Plugin;端口不同就改「集成 MCP 地址」,再点「重新读取」 |
179
+ | 「设置」里没有「Zotero 插件」这一页 | 插件没装成功或没重启 | 回「插件市场」确认已安装,然后重启 DSH |
180
+ | 划高亮 / 写笔记失败,提示未授权 | 第 5 步只开了开关、没点授权按钮 | 点「授权 Zotero 写权限」,弹窗里选「**始终允许**」 |
181
+ | 每写一次就弹一次授权框 | 上次选的是「允许」,拿到的是一次性凭据 | 重新点授权,这次选「始终允许」 |
182
+ | 授权按钮灰着点不动 | 上面的开关还没打开,或改动还没自动保存 | 先打开「允许写入 Zotero」,等「正在自动保存…」消失 |
183
+ | 让 AI 新建分类,报「写操作已禁用」 | Zotero 里那个 MCP 小插件没开写操作 | 到 Zotero 的 MCP 插件设置里勾选「允许写操作」,重试即可,不用重启 DSH |
184
+ | 提示「Zotero 里这条已经变了」 | 你(或 AI)在 Zotero 里同时改了同一条 | 刷新后重试;插件宁可报错也不覆盖你的新改动 |
185
+ | 草稿里的引用胶囊发送失败,说找不到来源 | 插件被禁用或卸载了,胶囊没人展开 | 重新启用插件,或把胶囊删掉再发 |
186
+ | 改了设置好像没生效 | 自动保存失败(顶部有红字) | 按红字提示再改一次任意字段触发重试;仍失败就看是不是被更高优先级配置覆盖 |
79
187
 
80
188
  ## 特性
81
189
 
82
- - **右侧栏面板「Zotero 文献库」**:与 Zotero 本体同构——顶部状态栏(Zotero / 模型工具探活 + 刷新),左侧分类树与标签面板,右侧是当前范围的条目列表;条目独立成列。分类树与条目列表之间的分隔条可拖动,宽度按本机记住。
190
+ - **右侧栏面板「Zotero 文献库」**:与 Zotero 本体同构——顶部状态栏(Zotero / 模型工具探活 + 刷新),左侧分类树与标签面板,右侧是当前范围的条目列表;条目独立成列。分类树与条目列表之间的分隔条可拖动,宽度按本机记住;**选中的分类与展开状态也按本机记住**,刷新页面或重开面板后回到上次的位置并重拉该目录的条目。
83
191
  - **分类筛选**:分类树顶部可按名称筛选目录(同 Zotero 左栏:只筛目录名,命中项与祖先保留、自动展开,不影响右侧条目搜索)。
84
192
  - **条目列表**:每行显示文献类型图标与作者 / 年份;读过的文献类型图标转为粉色、标题略淡,悬停补上类型名与最后阅读时间。单击选中、`Ctrl` / `Cmd` 点选多选,双击在右侧栏顶层开独立详情页,右键单行可直接插引用;头部搜索框针对当前范围(分类 / 全库 / 标签筛选后)按标题与摘要过滤,列表可分页「加载更多」,选中多条时右上角一次「引用 N」。
85
193
  - **标签面板**:树下方独立面板,可拖高 / 折叠;标签按 Zotero 的换行胶囊排布并跟随当前目录:选中分类时只列该分类自身条目里出现过的标签(不含子目录,自动标签弱化显示),选中文库根时列出全库标签;可按名称筛选、多选,并切换「全部(AND)/ 任一(OR)」。筛选作用于当前选择的范围,列表头部会显示已选标签胶囊与「清除筛选」;切换目录会自动清除已选标签,避免旧筛选作用到新范围。已选标签可从摘要行合并成一枚「标签组」胶囊引用。
@@ -92,40 +200,12 @@ curl http://127.0.0.1:23119/api/ # 期望输出:Zotero is running
92
200
  - **多种插入方式**:单条目、列表多选批量、单标签、多标签(合并成一枚「标签组」胶囊,AND/OR 在插入那一刻定格)与整目录引用都以「引用胶囊」写进草稿——胶囊只显示标题,发送那一刻才展开成完整引用文本,模型拿到的内容与以前一致;全文划词摘录、单条标注、单条笔记仍按纯文本插入。所有方式都只写进会话草稿(不自动发送、不抢焦点),文本携带 `itemKey` / `collectionKey` / 标签名供模型接续操作。标签类引用始终按全库范围展开,不受你当时选中哪个分类影响。
93
201
  - **胶囊依赖本插件展开**:草稿里留着引用胶囊时禁用或卸载本插件,发送会失败并提示找不到引用来源,把胶囊删掉即可继续正常发送。
94
202
  - **分类只读**:不提供任何新建 / 改名 / 删除分类的按钮——整理分类是模型的活,人在面板里只管浏览与引用。
95
- - **标注与笔记可写(默认关)**:配置卡打开「Zotero 写权限」并授权后,阅读页划选即写高亮 / 下划线(Zotero 色板七色 + 评论一次点明),点页内高亮弹出的标注卡片可当场「添加评论 / 改评论」,「标注」块还支持改色、改页码、加标签、高亮↔划线、删除,「笔记」块支持新建 / 编辑 / 删除。所有写入都直接进 Zotero 本地库,插件不存副本;含 Zotero 引文或标注锚点的笔记只给删除、不给编辑,改正文会让锚点失联。删除是**硬删**,不进 Zotero 回收站,面板里要点两次才会真删。开关关着时上述入口一个都不出现。
96
- - **模型侧工具可逐个开关**:插件自持连接集成 MCP,把工具以 `mcp__zotero__*` 注册进 dsh,可在插件页按工具启用 / 禁用。
203
+ - **标注与笔记可写(默认关)**:在「设置 → Zotero 插件」打开「Zotero 写权限」并授权后,阅读页划选即写高亮 / 下划线(Zotero 色板七色 + 评论一次点明),点页内高亮弹出的标注卡片可当场「添加评论 / 改评论」,「标注」块还支持改色、改页码、加标签、高亮↔划线、删除,「笔记」块支持新建 / 编辑 / 删除。所有写入都直接进 Zotero 本地库,插件不存副本;含 Zotero 引文或标注锚点的笔记只给删除、不给编辑,改正文会让锚点失联。删除是**硬删**,不进 Zotero 回收站,面板里要点两次才会真删。开关关着时上述入口一个都不出现。
204
+ - **模型侧工具可逐个开关**:插件自持连接集成 MCP,把工具以 `mcp__zotero__*` 注册进 dsh,可在「设置 → Zotero 插件 → MCP 工具」里逐项启用 / 禁用。
97
205
 
98
- ## 插件页配置项
206
+ ---
99
207
 
100
- 在 dsh 顶部的「插件」面板里展开 `dsh-plugin-zotero`,点组件行上的「配置 dsh-plugin-zotero」,即可调整连接参数。表单分两组。
101
-
102
- **API 设置**(本地 API 与面板行为)
103
-
104
- | 字段 | 默认 | 生效点 |
105
- |---|---|---|
106
- | `zoteroBaseUrl` | `http://127.0.0.1:23119` | Zotero 本地 API 探活与全部请求 |
107
- | `requestTimeoutMs` | `5000` | 单次本地 API 请求超时 |
108
- | `fulltextMaxBytes` | `204800` | 附件全文返回上限(超出截断) |
109
- | `defaultLimit` | `50` | 面板条目列表默认拉取条数 |
110
-
111
- **MCP 设置**(集成 MCP 连接与工具清单)
112
-
113
- | 字段 | 默认 | 生效点 |
114
- |---|---|---|
115
- | `mcpUrl` | `http://127.0.0.1:23120/mcp` | 集成 MCP 探活、工具列表与工具调用 |
116
- | `mcpProbeTimeoutMs` | `800` | TCP 探活集成 MCP 端口超时 |
117
- | `disabledMcpTools` | `[]` | 被停用的 MCP 工具**原始名**;模型侧据此过滤注册 |
118
-
119
- MCP 组下方是 **「MCP 工具」** 区:现场列出集成 MCP 的全部工具(`mcp__zotero__<原始名>` + 描述),每行右侧一个开关。关掉某个工具并保存后,模型侧不再注册它(等价于从模型的工具表里摘掉);「重新读取」可重拉清单。开启配置卡或保存后各同步一次工具注册。
120
-
121
- 保存与重置:
122
-
123
- - 保存写入 profile 的 patch 层 `~/.dsh/profiles/<profile>/cordis.patch.yml`。
124
- - 所有字段走 Schemastery `.volatile()`,只提交新值并唤醒引用,**无需重启**即时生效;工具开关同理(写进 `disabledMcpTools` 字段)。
125
- - 字段旁的「已覆盖」表示该值来自 patch 层而非默认值;点「恢复默认」清掉覆盖。若该值被更高优先级的 patch 层覆盖,保存会报「被覆盖」错误。
126
- - 「设置 → 内置插件」是只读清单,不提供编辑入口;配置入口只在「插件」面板。
127
-
128
- 实现:Host 半在 [src/index.ts](src/index.ts) 导出 `Config` schema、注入读取器([src/zotero/config.ts](src/zotero/config.ts) 的 `setSettingsReader`)并驱动 [src/host/mcp-bridge.ts](src/host/mcp-bridge.ts);Client 半在 [src/client/ZoteroCard.tsx](src/client/ZoteroCard.tsx) 渲染配置卡(席位 key `dsh-plugin-zotero#dsh-plugin-zotero`)。
208
+ 以下面向开发者与想折腾配置的人,普通使用可以不看。
129
209
 
130
210
  ## 架构
131
211
 
@@ -143,13 +223,13 @@ MCP 没起,面板照常可用;Zotero 没开,模型工具自然也不可用
143
223
  | 半边 | 代码位置 | 通道 |
144
224
  |---|---|---|
145
225
  | Host | `src/index.ts`、`src/host/`、`src/zotero/` | 把 Zotero 本地 API 包装成 HTTP 端点(读 + 受开关约束的写),挂在 DSH 宿主 web server 上 |
146
- | Client | `src/client/` | 在右侧栏注册 tab、面板正文与插件页配置卡,数据与选择状态放在模块级单例 |
226
+ | Client | `src/client/` | 在右侧栏注册 tab、面板正文,并在「设置」对话框注册独立一页;数据与选择状态放在模块级单例 |
147
227
 
148
228
  两条数据流:
149
229
 
150
230
  ```
151
231
  人侧 浏览器面板 ──同源 fetch──▶ /dsh-zotero/api/*(Host 路由)──HTTP──▶ Zotero 本地 API(127.0.0.1:23119)
152
- 模型侧 启动 / 配置卡打开 ──sync──▶ 集成 MCP(127.0.0.1:23120)──注册──▶ dsh 工具表(mcp__zotero__*)
232
+ 模型侧 启动 / 设置页打开 ──sync──▶ 集成 MCP(127.0.0.1:23120)──注册──▶ dsh 工具表(mcp__zotero__*)
153
233
  ```
154
234
 
155
235
  - Host 路由为 `GET /dsh-zotero/api/<action>`,action 有 `health` / `tree` / `items` / `tags` / `item` / `collection-bib` / `mcp-tools`。`items` 支持 `tag`(重复出现为 AND,`A || B` 为 OR)与 `q` 组合过滤。
@@ -178,8 +258,8 @@ src/ # 插件源码(主包,ESM / NodeNext / strict)
178
258
  │ ├── config.ts # 端点 / 超时 / 截断阈值 + 运行时设置读取器
179
259
  │ └── types.ts # Host ↔ Client 数据契约
180
260
  └── client/ # Client 半(浏览器)
181
- ├── index.ts # 注册右侧栏 tab(面板 + 条目详情)、面板正文与插件页配置卡
182
- ├── ZoteroCard.tsx # 插件页配置卡(API 设置 / MCP 设置 / 工具开关)
261
+ ├── index.ts # 注册右侧栏 tab(面板 + 条目详情)、面板正文与「设置」独立页
262
+ ├── ZoteroCard.tsx # 设置页正文(写权限 / API 设置 / MCP 设置 / 工具开关,防抖自动保存)
183
263
  ├── ZoteroPane.tsx # 面板容器:状态栏 + 分类树 / 标签面板 + 条目列表
184
264
  ├── CollectionTree.tsx / TagPanel.tsx / ItemList.tsx
185
265
  ├── SearchField.tsx # 目录筛选 / 条目搜索 / 标签筛选共用的紧凑搜索框
@@ -214,8 +294,8 @@ plugin_helloword/ # 官方插件示例(学习用,勿放正式代码
214
294
 
215
295
  - Node + **pnpm**(主包与 `tstest/` 统一用 pnpm,勿与 npm / yarn 混用)。
216
296
  - **TypeScript ^5.9**:`tsdown@0.22.0` 的 peer 依赖不支持 TypeScript 7.x。
217
- - Zotero 桌面版已运行,且已开启本地 API(见[使用前提](#使用前提))。
218
- - **模型侧必需**:Zotero 已安装集成 MCP 插件(插件市场中的 **Zotero MCP Plugin** / `zotero-integrated-mcp`),监听 23120——若用其他 MCP 插件或端口不同,需在插件配置卡改 `mcpUrl`;并在 MCP 插件设置中**开启「允许写操作」**。只装插件不开写操作时,模型侧读类工具照常,但让模型新建 / 修改分类会直接报错(插件返回「写操作已禁用」)。详见[模型侧 MCP 与权限边界](#模型侧-mcp-与权限边界)。
297
+ - Zotero 桌面版已运行,且已开启本地 API(见[第 3 步](#第-3-步打开-zotero-的本机通信开关))。
298
+ - **模型侧必需**:Zotero 已安装集成 MCP 插件(插件市场中的 **Zotero MCP Plugin** / `zotero-integrated-mcp`),监听 23120——若用其他 MCP 插件或端口不同,需在设置页改「集成 MCP 地址」(`mcpUrl`);并在 MCP 插件设置中**开启「允许写操作」**。只装插件不开写操作时,模型侧读类工具照常,但让模型新建 / 修改分类会直接报错(插件返回「写操作已禁用」)。详见[模型侧 MCP 与权限边界](#模型侧-mcp-与权限边界)。
219
299
  - `dsh` CLI 可用。
220
300
 
221
301
  ## 构建
@@ -251,29 +331,37 @@ dsh --profile demo # 启动
251
331
 
252
332
  客户端 bundle **没有热更新**:改完必须重启 dsh 并重新加载页面。
253
333
 
254
- ## 配置
334
+ ## 配置层与权限实现
335
+
336
+ 界面操作见[安装与设置](#安装与设置)与[设置项说明](#设置项说明设置--zotero-插件),这里只记实现。
255
337
 
256
- ### 开启 Zotero 本地 API
338
+ ### 设置怎么落盘
257
339
 
258
- 见[使用前提 → 开启 Zotero 本地 API](#2-开启-zotero-本地-api)。未勾选时读端点返回 403,面板显示「Zotero 未连接」并提示启用步骤。
340
+ - 入口是「设置」对话框的 `settings.section` 席位(section id `zotero`,`order: 30`,排在框架自带各页之后),仅当 Host 服务本插件的 settings 命名空间时才注册。命名空间 id `dsh-plugin-zotero` 必须与 [cordis.patch.yml](cordis.patch.yml) 的 insert 行 id 保持同步。
341
+ - **表单没有保存按钮**:最后一次改动后防抖 600ms 落盘;离开页面时合法草稿立刻冲盘、非法草稿直接丢弃;写盘失败**不自动重试**(否则每 600ms 打一次后端),等用户下一次编辑。
342
+ - 落盘目标是 profile 的 patch 层 `~/.dsh/profiles/<profile>/cordis.patch.yml`。所有字段走 Schemastery `.volatile()`,只提交新值并唤醒引用,**无需重启**即时生效。
343
+ - 表单里露出的六个字段与界面标签的对照见[设置项说明](#设置项说明设置--zotero-插件)。另有两个不以文本框形式露出的字段:`writeEnabled`(布尔,写权限总开关)、`disabledMcpTools`(字符串数组,被停用的 MCP 工具**原始名**,由「MCP 工具」区的开关维护,模型侧据此过滤注册)。
344
+ - 「已覆盖」表示该值来自 patch 层而非默认值,「恢复默认」清掉覆盖;若被更高优先级的 patch 层覆盖,保存会报「被覆盖」错误。「设置 → 内置插件」是只读清单,不提供编辑入口。
345
+ - 实现:Host 半在 [src/index.ts](src/index.ts) 导出 `Config` schema、注入读取器([src/zotero/config.ts](src/zotero/config.ts) 的 `setSettingsReader`)并驱动 [src/host/mcp-bridge.ts](src/host/mcp-bridge.ts);Client 半在 [src/client/ZoteroCard.tsx](src/client/ZoteroCard.tsx) 渲染表单,由 [src/client/index.ts](src/client/index.ts) 注册席位。一次写入落地后重取工具清单与写权限状态。
259
346
 
260
347
  ### 模型侧 MCP 与权限边界
261
348
 
262
349
  模型侧工具由**插件自己**桥接:[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` 会与自注册工具重名冲突。
263
350
 
264
- ⚠️ 前提是 [Zotero 里已装好集成 MCP 插件](#1-安装-zotero-mcp-插件)(或改用其他 MCP 插件并在配置卡填对 `mcpUrl`),并且开启了「允许写操作」。插件未安装或服务未起时,模型侧工具全部不可用;插件装了但没开写操作时,读类工具正常,`create_collection` 等写工具会被插件拒绝(返回「写操作已禁用」),表现为让模型帮忙新建分类直接报错——此时到 MCP 插件设置里打开写操作并重试即可,无需重启 dsh。
351
+ ⚠️ 前提是 [Zotero 里已装好集成 MCP 插件](#第-2-步给-zotero-装一个桥接小插件)(或改用其他 MCP 插件并在设置页填对 `mcpUrl`),并且开启了「允许写操作」。插件未安装或服务未起时,模型侧工具全部不可用;插件装了但没开写操作时,读类工具正常,`create_collection` 等写工具会被插件拒绝(返回「写操作已禁用」),表现为让模型帮忙新建分类直接报错——此时到 MCP 插件设置里打开写操作并重试即可,无需重启 dsh。
265
352
 
266
- ⚠️ 模型的写能力有两处来源,都要单独关才收得住:集成 MCP 的 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 工具」里逐个关掉;标注与笔记的写是插件自有的 `zotero_update_annotation` / `zotero_delete_annotation` / `zotero_create_note` / `zotero_update_note` / `zotero_delete_note` 五个工具,它们只在「Zotero 写权限」开关打开时才注册,关掉即从模型的工具表里消失。面板侧的分类操作始终只读。
353
+ ⚠️ 模型的写能力有两处来源,都要单独关才收得住:集成 MCP 的 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 工具」里逐个关掉;标注与笔记的写是插件自有的 `zotero_update_annotation` / `zotero_delete_annotation` / `zotero_create_note` / `zotero_update_note` / `zotero_delete_note` 五个工具,它们只在「Zotero 写权限」开关打开时才注册,关掉即从模型的工具表里消失。面板侧的分类操作始终只读。
267
354
 
268
355
  **写操作为什么优先走 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) 里给所有写工具的描述统一注入了「首选写通道」引导语,并点明标注 / 笔记这两类 MCP 做不到、只能走插件自带的 `zotero_*` 工具;「导入本地文件并挂到某条目下」用 `write_item` 的 `action: "import"` + `filePath` + `parentItemKey`,一条工具调用即可。
269
356
 
270
357
  ### 写权限与授权
271
358
 
272
- 写能力默认全关,开启路径是「插件」页配置卡 → 「Zotero 写权限」:
359
+ 点击路径见[第 5 步](#第-5-步可选想让-ai-帮你改文献库)。机制上分两道闸:`writeEnabled` 决定面板写入口与模型侧 `zotero_*` 工具**是否注册**,本地 API key 决定 Zotero **认不认**这次写入,两者缺一不可。
273
360
 
274
- 1. 打开「允许在 DSH 里修改 Zotero 文库」并保存 —— 面板的写入口与模型侧的 `zotero_*` 工具同时出现。
275
- 2. 点「授权 Zotero 写权限」,Zotero 会弹一次「本地 API 授权」框,**请选「始终允许」**。选「允许」拿到的 key 是一次性的,第二条写就断。
276
- 3. 「始终允许」的长期 key 会存到本机 `~/.dsh/storages/dsh-plugin-zotero/local-api-key.json`(`0600`,只在 Host 进程内读写,不进配置存储、不在表单里回显),之后**重启 dsh / 重启 Zotero 都直接复用,不用再点授权**。升级到带本功能的新版本时,会自动从 Zotero 自己的密钥库(profile 下的 `localAPIKeys.json`)导入此前点过的「始终允许」,同样不需要再点一次。撤销授权在 Zotero 侧做即可:下一次写入收到 401,插件随即删掉本地副本并回到「未授权」。
361
+ - 授权走 `POST /api/local/authorize`,Zotero 弹框会挂住这条请求直到用户点按钮,因此等待期间按钮禁用(再点只是多弹一个框,还可能撞上 Zotero 每分钟 5 次的授权限流)。
362
+ - 选「始终允许」拿到的长期 key 存到 `~/.dsh/storages/dsh-plugin-zotero/local-api-key.json`(`0600`,只在 Host 进程内读写,不进配置存储、不在表单里回显),之后**重启 dsh / 重启 Zotero 都直接复用**。选「允许」拿到的是一次性 key,首个写请求即被 Zotero 删除。
363
+ - 升级到带本功能的新版本时,会自动从 Zotero 自己的密钥库(profile 下的 `localAPIKeys.json`)导入此前点过的「始终允许」,不需要再点一次。
364
+ - 撤销在 Zotero 侧做即可:下一次写入收到 401,插件随即删掉本地副本并回到「未授权」。拿到长期授权后主按钮降级为「重新授权」,正常路径下不需要再点。
277
365
 
278
366
  写请求一律带并发前置条件(条目版本),撞上并发改动返回「Zotero 里这条已经变了」而不是覆盖;删除类操作在面板里必须点两次(「删除」→「确认删除」)才会真删,且是硬删、不进回收站。含 Zotero 引文 / 标注锚点的笔记不能编辑,只能删除。出问题时的止血手段仍是那个开关:关掉即彻底回到严格只读。
279
367