前言¶
在 DSH 里写论文综述、做文献问答时，常见做法是手动复制题录或把 PDF 丢进对话。Zotero 里已有分类、附件和全文，却和会话草稿脱节；若要让模型检索文库，还要单独配 MCP、担心工具名冲突和权限边界。下面介绍社区插件 dsh-plugin-zotero（维护者 peijiping），它基于 cordis，用「人侧只读面板 + 模型侧自持 MCP 桥接」两条通道，把本机 Zotero 接到 DSH，职责分开、互不依赖。
这是什么¶
dsh-plugin-zotero 是 DSH 的客户端类插件：在右侧栏提供「Zotero 文献库」面板，通过宿主 web server 自注册的 /dsh-zotero/api/* 只读访问 Zotero 本地 API；同时插件自己连接本机 Zotero 集成 MCP，把工具以 mcp__zotero__* 注册给模型，并支持在插件页按工具逐个开关。MCP 未启动时面板仍可用；Zotero 未运行时模型侧工具自然不可用。当前 npm 包版本为 0.1.2，许可证 MIT，GitHub 约 6 stars。分类与索引见 SkillHub 目录页，源码与说明见 GitHub 仓库。
核心功能¶
人侧：右侧栏只读面板¶
面板分三块（仓库 README 有截图说明）：
- 顶部状态栏：显示 Zotero 是否已连接、模型工具是否可用，并提供刷新。
- 左侧分类树：按 Zotero 分类逐级浏览，支持按标题 / 摘要搜索。
- 右侧详情：展示条目元数据、附件与全文。
向当前会话草稿插入内容有三种方式，均不自动发送、不抢焦点，文本会携带 itemKey / collectionKey 供模型接续操作：
- 单条目引用（「添加条目引用」）。
- 全文划词摘录。
- 整目录引用。
面板严格只读：不提供新建、改名、删除分类等写操作按钮。
模型侧：集成 MCP 与工具开关¶
插件通过 mcp-bridge 直连本机 Zotero 集成 MCP（默认 http://127.0.0.1:23120/mcp），按配置中的 disabledMcpTools 过滤后注册工具。README 注明：集成 MCP 实测版本 zotero-integrated-mcp v1.1.0 暴露约 20 个工具，其中 5 个会改变文库结构（如 create_collection、delete_collection 等）。若希望模型侧尽量只读，可在插件页「MCP 工具」区关掉对应工具并保存；面板功能不受影响。
Host 侧对 /dsh-zotero/api/* 有信任栅栏：仅接受 GET、拒绝跨站 sec-fetch-site，且 Host 须为回环地址，用于降低 DNS rebinding 风险。
安装与启用¶
环境要求¶
- dsh 版本满足
>=0.2.0-rc.2 <0.3.0-0（package.json的engines.dsh）。 - Zotero 桌面版已运行，并开启本地 API（见下文「Zotero 本地 API」）。
- （可选）本机 Zotero 集成 MCP 监听 23120，供模型侧工具使用。
从 npm 安装时包内为预构建产物（lib/ + client/client.js），不运行构建脚本，无需 allowBuilds 授权。
安装命令¶
# 从 npm（推荐）
dsh plugin --profile <profile> add dsh-plugin-zotero
也可在 dsh 插件页通过市场索引源安装（README 示例索引：https://awesome-dsh-plugin.com/index.json）。
安装后启动对应 profile 的 dsh，在浏览器打开终端打印的 web 地址（profile 默认常为 http://127.0.0.1:3080，以实际配置为准）。
开启 Zotero 本地 API¶
- 打开 Zotero → 设置 → 高级。
- 勾选 「允许本机其他应用与 Zotero 通信」（默认端口 23119，仅回环监听）。
验证：
curl http://127.0.0.1:23119/api/
期望输出：Zotero is running。未勾选时读端点可能返回 403，面板会显示「Zotero 未连接」并提示启用步骤。
插件页配置¶
在 dsh 顶部 「插件」 面板展开 dsh-plugin-zotero，点 「配置 dsh-plugin-zotero」。主要字段如下（保存写入 ~/.dsh/profiles/<profile>/cordis.patch.yml，无需重启即可生效）：
API 设置
| 字段 | 默认 | 说明 |
|---|---|---|
zoteroBaseUrl |
http://127.0.0.1:23119 |
本地 API 探活与请求 |
requestTimeoutMs |
5000 |
单次请求超时 |
fulltextMaxBytes |
204800 |
附件全文返回上限（超出截断） |
defaultLimit |
50 |
面板列表默认条数 |
MCP 设置
| 字段 | 默认 | 说明 |
|---|---|---|
mcpUrl |
http://127.0.0.1:23120/mcp |
集成 MCP 探活与调用 |
mcpProbeTimeoutMs |
800 |
TCP 探活超时 |
disabledMcpTools |
[] |
被停用的 MCP 工具原始名列表 |
「MCP 工具」区可逐项开关；关闭并保存后，模型侧不再注册该工具。
典型用法¶
- 浏览与引用：右侧栏打开「Zotero 文献库」→ 在分类树中选条目或搜索 → 在详情区使用「添加条目引用」或划词摘录 → 内容进入当前会话草稿，再自行编辑或发送。
- 整目录引用：在分类上执行整目录引用，把目录结构相关信息写入草稿，便于让模型按
collectionKey继续检索或归纳。 - 模型检索与精读：确认集成 MCP 已运行且所需
mcp__zotero__*工具已启用 → 在对话中让模型调用工具检索、读全文或（若未关闭写工具）维护分类；写工具默认全开，按需收紧。
无活跃会话时，仍可通过右侧栏 guide 入口打开「Zotero 文献库」面板。更完整的入口说明、交互与 toast / 错误对照见仓库内 插件使用说明。
适用场景与注意¶
适合谁：日常用 Zotero 管理文献、又在 DSH 里写长文或做文献向问答的用户；希望面板浏览与模型工具共用同一套本机文库，且能单独关掉危险写工具的场景。
权限与安全：插件以当前 dsh 进程权限运行，会访问本机 127.0.0.1 上的 Zotero API 与 MCP。安装前建议阅读 源码 与 MIT 许可证，确认符合你的安全策略。社区目录 SkillHub 与 DeepSeek / 幻方无官方从属关系，插件来自社区维护者。
与「只读」相关的边界：UI 面板只读；模型侧是否只读取决于你启用了哪些 MCP 工具。MCP 未起不影响面板只读浏览。
结尾¶
dsh-plugin-zotero 把 Zotero 本地文库拆成「人侧草稿引用」和「模型侧可开关工具」两条线，减少手工搬运题录，并在插件页集中管理 API 与 MCP 参数。需要索引与简介时可打开 SkillHub 插件页；安装、配置与架构细节以 GitHub README 及 docs/ 下文档为准。
