dsh-plugin-zotero 0.0.0-stage → 0.1.2

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 peijiping
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,191 @@
1
- # Temporary Holding Version
1
+ # dsh-plugin-zotero
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 基于 [cordis](https://github.com/deepseek-ai/cordis) 的 DSH 插件,把本机 Zotero 文献库接进 DSH。分两半,职责不重叠、互不依赖:
4
+
5
+ | 半边 | 能力 | 通道 |
6
+ |---|---|---|
7
+ | **人侧面板** | 在 DSH 右侧栏只读浏览 Zotero 文库(分类树 / 搜索 / 条目详情 / PDF 全文),把条目、摘录或整目录引用写进会话草稿 | 插件在宿主 web server 自注册的 `/dsh-zotero/api/*` 路由 |
8
+ | **模型侧** | 检索、精读、按需操作文库 | 插件**自持**连接本机 Zotero 集成 MCP,工具以 `mcp__zotero__*` 注册给模型 |
9
+
10
+ MCP 没起,面板照常可用;Zotero 没开,模型工具自然也不可用。
11
+
12
+ > 面向使用者的完整说明(入口、交互、toast 与错误对照表)见 [插件使用说明](docs/插件使用说明/dsh-plugin-zotero使用说明.zh.md)。
13
+
14
+ ## 安装
15
+
16
+ 要求 dsh ≥ 0.2.0-rc.2(`package.json` 的 `engines.dsh` 为 `>=0.2.0-rc.2 <0.3.0-0`)。
17
+
18
+ ```sh
19
+ # 从 npm(推荐)
20
+ dsh plugin --profile <profile> add dsh-plugin-zotero
21
+
22
+ # 或从插件市场安装:dsh 插件页 → 发现 → 添加索引源
23
+ # https://awesome-dsh-plugin.com/index.json
24
+ ```
25
+
26
+ 包内是预构建产物(`lib/` + `client/client.js`),安装时**不运行构建脚本**,无需 `allowBuilds` 授权。本地源码开发见[方案一:本地路径安装](docs/插件发布/方案一本地路径安装.zh.md)。
27
+
28
+ ## 特性
29
+
30
+ - **右侧栏面板「Zotero 文献库」**:顶部状态栏(Zotero / 模型工具探活)+ 左侧分类树(按需拉取、标题摘要搜索)+ 右侧条目详情或分类概要。
31
+ - **三种插入方式**:单条目引用、全文划词摘录、整目录引用,均只写进会话草稿(不自动发送、不抢焦点),文本携带 `itemKey` / `collectionKey` 供模型接续操作。
32
+ - **面板严格只读**:不提供任何新建 / 改名 / 删除分类的按钮。
33
+ - **模型侧工具可逐个开关**:插件自持连接集成 MCP,把工具以 `mcp__zotero__*` 注册进 dsh,可在插件页按工具启用 / 禁用。
34
+
35
+ ## 插件页配置项
36
+
37
+ 在 dsh 顶部的「插件」面板里展开 `dsh-plugin-zotero`,点组件行上的「配置 dsh-plugin-zotero」,即可调整连接参数。表单分两组。
38
+
39
+ **API 设置**(本地 API 与面板行为)
40
+
41
+ | 字段 | 默认 | 生效点 |
42
+ |---|---|---|
43
+ | `zoteroBaseUrl` | `http://127.0.0.1:23119` | Zotero 本地 API 探活与全部请求 |
44
+ | `requestTimeoutMs` | `5000` | 单次本地 API 请求超时 |
45
+ | `fulltextMaxBytes` | `204800` | 附件全文返回上限(超出截断) |
46
+ | `defaultLimit` | `50` | 面板条目列表默认拉取条数 |
47
+
48
+ **MCP 设置**(集成 MCP 连接与工具清单)
49
+
50
+ | 字段 | 默认 | 生效点 |
51
+ |---|---|---|
52
+ | `mcpUrl` | `http://127.0.0.1:23120/mcp` | 集成 MCP 探活、工具列表与工具调用 |
53
+ | `mcpProbeTimeoutMs` | `800` | TCP 探活集成 MCP 端口超时 |
54
+ | `disabledMcpTools` | `[]` | 被停用的 MCP 工具**原始名**;模型侧据此过滤注册 |
55
+
56
+ MCP 组下方是 **「MCP 工具」** 区:现场列出集成 MCP 的全部工具(`mcp__zotero__<原始名>` + 描述),每行右侧一个开关。关掉某个工具并保存后,模型侧不再注册它(等价于从模型的工具表里摘掉);「重新读取」可重拉清单。开启配置卡或保存后各同步一次工具注册。
57
+
58
+ 保存与重置:
59
+
60
+ - 保存写入 profile 的 patch 层 `~/.dsh/profiles/<profile>/cordis.patch.yml`。
61
+ - 所有字段走 Schemastery `.volatile()`,只提交新值并唤醒引用,**无需重启**即时生效;工具开关同理(写进 `disabledMcpTools` 字段)。
62
+ - 字段旁的「已覆盖」表示该值来自 patch 层而非默认值;点「恢复默认」清掉覆盖。若该值被更高优先级的 patch 层覆盖,保存会报「被覆盖」错误。
63
+ - 「设置 → 内置插件」是只读清单,不提供编辑入口;配置入口只在「插件」面板。
64
+
65
+ 实现: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`)。
66
+
67
+ ## 架构
68
+
69
+ | 半边 | 代码位置 | 通道 |
70
+ |---|---|---|
71
+ | Host | `src/index.ts`、`src/host/`、`src/zotero/` | 把 Zotero 本地 API 包装成只读 HTTP 端点,挂在 DSH 宿主 web server 上 |
72
+ | Client | `src/client/` | 在右侧栏注册 tab、面板正文与插件页配置卡,数据与选择状态放在模块级单例 |
73
+
74
+ 两条数据流:
75
+
76
+ ```
77
+ 人侧 浏览器面板 ──同源 fetch──▶ /dsh-zotero/api/*(Host 路由)──HTTP──▶ Zotero 本地 API(127.0.0.1:23119)
78
+ 模型侧 启动 / 配置卡打开 ──sync──▶ 集成 MCP(127.0.0.1:23120)──注册──▶ dsh 工具表(mcp__zotero__*)
79
+ ```
80
+
81
+ - Host 路由为 `GET /dsh-zotero/api/<action>`,action 有 `health` / `tree` / `items` / `item` / `collection-bib` / `mcp-tools`。
82
+ - Host 侧带信任栅栏:仅接受 GET,拒绝 `sec-fetch-site: cross-site`,且 `Host` 必须是回环地址(防 DNS rebinding)。
83
+ - 响应统一信封 `{ok:true,data}` / `{ok:false,error:{code,message}}`,错误码见 [src/zotero/types.ts](src/zotero/types.ts)。
84
+ - 面板正文会被每个会话各挂一份,因此分类树 / 搜索词 / 选中项等状态放在 [src/client/paneStore.ts](src/client/paneStore.ts) 的模块级单例里,各会话看到的是同一块面板;右侧栏的展开状态与 tab 则**按会话**持久。
85
+ - 无会话时面板仍可通过右侧栏的 guide 入口(「Zotero 文献库」)打开。
86
+
87
+ ## 目录结构
88
+
89
+ ```
90
+ src/ # 插件源码(主包,ESM / NodeNext / strict)
91
+ ├── index.ts # Host 半入口:Config schema、HTTP 路由、MCP 桥接装配
92
+ ├── host/
93
+ │ ├── router.ts # 只读 HTTP 路由 GET /dsh-zotero/api/<action>
94
+ │ └── mcp-bridge.ts # 自持集成 MCP 连接 + 按开关过滤注册模型工具
95
+ ├── zotero/
96
+ │ ├── client.ts # Zotero 本地 API 客户端(只读)+ 集成 MCP JSON-RPC
97
+ │ ├── config.ts # 端点 / 超时 / 截断阈值 + 运行时设置读取器
98
+ │ └── types.ts # Host ↔ Client 数据契约
99
+ └── client/ # Client 半(浏览器)
100
+ ├── index.ts # 注册右侧栏 tab、面板正文与插件页配置卡
101
+ ├── ZoteroCard.tsx # 插件页配置卡(API 设置 / MCP 设置 / 工具开关)
102
+ ├── ZoteroPane.tsx # 面板容器:状态栏 + 分类树 + 详情
103
+ ├── CollectionTree.tsx / ItemDetail.tsx
104
+ ├── paneStore.ts # 跨会话共享的面板状态
105
+ ├── inline.ts # 往会话草稿插入文本
106
+ ├── compose.ts # 插入文本模板
107
+ ├── api.ts # 调 Host 端点
108
+ └── locales.ts # zh / en 文案
109
+
110
+ client/client.js # tsdown 产物(勿手改)
111
+ lib/ # tsc 产物(勿手改)
112
+ cordis.patch.yml # bundle patch 层:把本插件插入 profile 层栈
113
+ docs/ # 使用说明、Zotero API / MCP 参考、发布与 node 学习笔记
114
+ tstest/ # 独立测试沙盒(commonjs + tsx,与主包隔离)
115
+ plugin_helloword/ # 官方插件示例(学习用,勿放正式代码)
116
+ .trae/documents/ # 设计与实施方案(本地,未纳入版本控制)
117
+ ```
118
+
119
+ 主包与子项目分别有各自的 `package.json`;测试沙盒 `tstest/` 环境独立,其依赖不得引入主包。
120
+
121
+ ## 环境要求
122
+
123
+ - Node + **pnpm**(主包与 `tstest/` 统一用 pnpm,勿与 npm / yarn 混用)。
124
+ - **TypeScript ^5.9**:`tsdown@0.22.0` 的 peer 依赖不支持 TypeScript 7.x。
125
+ - Zotero 桌面版已运行,且已开启本地 API(见「配置」)。
126
+ - (模型侧可选)本机 Zotero 集成 MCP 服务监听 23120。
127
+ - `dsh` CLI 可用。
128
+
129
+ ## 构建
130
+
131
+ ```sh
132
+ pnpm install
133
+ pnpm build # tsc:src/ -> lib/(Host 半边)
134
+ pnpm build:client # tsdown:src/client/ -> client/client.js(Client 半边)
135
+ pnpm typecheck:client # tsc --noEmit 校验客户端源码
136
+ ```
137
+
138
+ ## 本地测试启动
139
+
140
+ 本地路径 link 的完整操作见 [方案一:本地路径安装](docs/插件发布/方案一本地路径安装.zh.md),核心三步:
141
+
142
+ ```sh
143
+ dsh plugin --profile demo add ./
144
+ dsh --profile demo --dump-config # 应能看到 dsh-plugin-zotero 一行
145
+ dsh --profile demo # 启动
146
+ ```
147
+
148
+ - **访问地址**:启动后终端会打印 URL(web server 配置 `printUrl: true`),浏览器打开 **http://127.0.0.1:3080**。该地址来自 profile 组合配置里的 web server(`host` 默认 `127.0.0.1`、`port` 默认 `3080`),不是固定端口之外另开的服务。
149
+ - **命令来源**:`dsh` 是桌面 App 自带的 CLI(如 `/usr/local/bin/dsh`);仓库里也装了同一 CLI 的 devDependency,等价写法是 `pnpm dsh --profile demo`,两者读同一个 `~/.dsh/profiles/demo`。
150
+ - **启动前**:Host 半边与 Client 半边加载的都是构建产物(`lib/`、`client/client.js`),改完 `src/` 要先按上一节构建,再重启 dsh(见「日常迭代」)。
151
+
152
+ ## 日常迭代
153
+
154
+ | 改了什么 | 要做什么 |
155
+ |---|---|
156
+ | `src/`(Host 半边) | `pnpm build` → 重启 dsh |
157
+ | `src/client/`(Client 半边) | `pnpm build:client` → 重启 dsh → 浏览器重新打开页面 |
158
+ | `cordis.patch.yml` | 重启 dsh |
159
+
160
+ 客户端 bundle **没有热更新**:改完必须重启 dsh 并重新加载页面。
161
+
162
+ ## 配置
163
+
164
+ ### 开启 Zotero 本地 API
165
+
166
+ Zotero → 设置 → 高级 → 勾选 **「允许本机其他应用与 Zotero 通信」**(默认端口 23119,仅监听回环)。验证:
167
+
168
+ ```sh
169
+ curl http://127.0.0.1:23119/api/ # 期望输出:Zotero is running
170
+ ```
171
+
172
+ 未勾选时读端点返回 403,面板显示「Zotero 未连接」并提示启用步骤。
173
+
174
+ ### 模型侧 MCP 与权限边界
175
+
176
+ 模型侧工具由**插件自己**桥接:[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` 会与自注册工具重名冲突。
177
+
178
+ ⚠️ 面板只读,**但模型侧工具不是**:20 个工具中含 5 个改变文库结构的写工具(`create_collection` / `update_collection` / `delete_collection` / `add_items_to_collection` / `remove_items_from_collection`)。想收紧为纯只读,直接在插件页配置卡的「MCP 工具」里关掉它们并保存即可;面板功能不受影响。
179
+
180
+ ## 相关文档
181
+
182
+ - [插件使用说明](docs/插件使用说明/dsh-plugin-zotero使用说明.zh.md) — 入口、交互、toast 与错误对照表
183
+ - [Zotero 本地 API 参考](docs/Zotero文档/Zotero本地API参考.md)
184
+ - [Zotero 集成 MCP 服务参考](docs/Zotero文档/Zotero集成MCP服务参考.md)
185
+ - [方案一:本地路径安装](docs/插件发布/方案一本地路径安装.zh.md)
186
+ - [DSH 插件开发文档](docs/DSH插件开发文档/README.zh.md)
187
+ - [开发与设计方案](.trae/documents/Zotero-DSH插件开发与设计方案.md)(本地)
188
+
189
+ ## License
190
+
191
+ [MIT](LICENSE)