前言¶
在 DSH 裏做文獻相關對話時，模型本身拿不到你 Zotero 裏的條目、附件索引和當前選中的分類。常見做法是手動複製標題、DOI 或 BibTeX，或另開腳本調 Zotero 本地 API，再把結果貼回對話。dsh-zotero 把搜索、讀索引全文、導入 RIS/BibTeX、導出參考文獻和插入引用收進 DSH 的 zotero 技能，通過本機 HTTP 連正在運行的 Zotero Desktop，不依賴雲端 Zotero Key，也不額外起一個 MCP 服務。
下面按「是什麼 → 能做什麼 → 怎麼裝 → 怎麼用 → 注意點」說明。事實以倉庫 README 與 package.json 爲準；社區目錄頁見文末鏈接。
這是什麼¶
dsh-zotero（npm 包名 dsh-zotero，當前發佈版本 0.2.0）由維護者 chanhaoxian5-ship-it 發佈，在 DeepSeek Harness 中註冊 zotero 技能。它在 OpenAI Zotero plugin 0.1.2 之上做 DSH 適配，保留原插件與原始 Python 腳本，並按 DSH 官方 bundle 格式分發。
在 SkillHub 等社區目錄中，該插件歸類爲「記憶」——含義是：對話可以基於你本機已索引的文庫與附件文本，而不是每次從零粘貼摘要。
環境要求¶
安裝前確認下列條件（README 原文）：
- DSH 版本
>=0.2.1-rc.5且<0.3.0，profile 中需啓用skills服務。 - Node.js
>=22，Python>=3.10。 - Zotero Desktop 正在運行，本地 API 已啓用；默認地址爲
http://127.0.0.1:23119。
README 記載的實際驗證環境爲 Windows、DSH 0.2.1-rc.5、Zotero 10.0.6。適配層在 Windows/Linux CI 中通過；macOS 與實際模型對話調用尚未驗收。
可選環境變量：
ZOTERO_LOCAL_BASE_URL：修改本地 API 地址。ZOTERO_PYTHON：指定 Python 解釋器路徑（不要附加參數）；未設置時優先 DSH 自帶 Python，再嘗試 PATH 上的 Python。ZOTERO_DSH_STATE_DIR：導入狀態目錄，默認~/.dsh/state/dsh-zotero。
核心功能¶
以下能力均來自 README，未在資料中出現的功能不寫。
搜索與瀏覽
- 在 personal 或指定羣組文庫中搜索；0.2.0 適配層修復了原腳本 DOI 搜索漏命中，搜索會完整分頁讀取文庫並返回 DOI 和分類 key。
- 通過 Zotero 文本索引讀取附件正文；圖表、掃描件和版式仍可能需要 PDF 閱讀工具。插件不內置外部 DOI 元數據解析、全文或補充材料下載器。
導入與導出
- 導入 RIS；BibTeX 若含宏、字符串拼接、指令或標題內 TeX 命令，文檔要求改用字面值 BibTeX 或 RIS。
- 導出參考文獻（例如對話中要求生成
references.bib）。 - 安全導入目前只支持個人文庫；羣組場景的搜索、inventory 和 duplicates 可顯式指定
--library groups/數字ID。
導入可靠性（CLI）
除對話示例外，倉庫提供 run-zotero.mjs 子命令做計劃導入、執行導入、查狀態和查重複，詳見下文「導入可靠性」一節。
組成概要
| 組件 | 作用 |
|---|---|
index.mjs |
DSH 原生技能提供器，註冊 zotero |
skills/zotero/scripts/zotero_dsh.py |
完整掃描、身份覈對、導入記錄、併發鎖和回讀驗證 |
skills/zotero/scripts/zotero.py |
原始 Zotero API / Connector 腳本 |
讀取與導入經本機 HTTP 完成；送入模型的文本仍由所選模型服務處理。插件以當前 DSH 進程權限運行，安裝前應自行查看源碼與 MIT 許可證（見倉庫 LICENSE、NOTICE.md）。
安裝與啓用¶
先在終端執行官方安裝命令（只在你準備好安裝時運行）：
dsh plugin --profile desktop add 'github:chanhaoxian5-ship-it/dsh-zotero#v0.2.0'
DSH 會根據包內 dsh.bundle 聲明維護 profile 的依賴與 bundles，無需手工改 profile，也無需把 skill 複製到全局目錄。插件直接分發可運行的 .mjs 和 .py，沒有安裝構建腳本。本項目目前未發佈到 npm。
查看組合配置是否已包含該插件：
dsh --profile desktop --dump-config
確認輸出中出現 dsh-zotero 後，重新啓動 DSH。若 dsh 不在 PATH，可使用桌面安裝目錄下的 resources/runtime/cli/bin/dsh.cmd。若 profile 裏其他插件有版本兼容性錯誤，須先處理；這與 Zotero 本地 API 是否可連是兩項獨立檢查。
也可從 GitHub Releases 下載 .tgz，再執行：
dsh plugin --profile desktop add 'D:/下載目錄/dsh-zotero-0.2.0.tgz'
需要不可變來源時，用發佈提交的完整 SHA 替代 #v0.2.0。
卸載：
dsh plugin --profile desktop remove dsh-zotero
典型用法¶
安裝並重啓後，在新對話中可以用自然語言觸發技能。README 示例：
用 zotero 技能搜索我的文庫中關於 retron 的論文。
更多可復現表述：
- 「用 zotero 搜索 cross-species retron，列出標題、年份和條目 key。」
- 「讀取這篇論文的 PDF 正文，先檢查附件和索引覆蓋情況。」
- 「把這條已覈對的 RIS 文獻加入 Zotero 當前分類，先檢查是否重複。」
- 「把選中的文獻導出成 references.bib。」
連接 Zotero 後，可用 CLI 做快速檢查（需 Zotero 已啓動）：
node skills/zotero/scripts/run-zotero.mjs status --json
node skills/zotero/scripts/run-zotero.mjs search 'cross-species retron' --json
路徑相對於插件安裝後的 skill 目錄；在已安裝環境中通常由 DSH 解析，開發時可於倉庫根目錄對照 README 執行。
導入可靠性¶
大批量或腳本化導入時，README 推薦先 plan 再 import，並用 status 覈對，避免盲目重發：
node skills/zotero/scripts/run-zotero.mjs plan-import --format ris --file 'D:/論文/paper.ris'
node skills/zotero/scripts/run-zotero.mjs import-ris --file 'D:/論文/paper.ris' --yes
node skills/zotero/scripts/run-zotero.mjs import-status
node skills/zotero/scripts/run-zotero.mjs duplicates
文檔說明的要點：
- 全文庫按規範化 DOI 去重；已有條目在其他分類也會跳過；批次內同 DOI 重複也會跳過。
- 僅同標題或 DOI 衝突的條目暫停覈查，避免誤合併預印本與正式版。
- 讀失敗、分頁不完整、文庫版本變化或目標分類切換時會停止；不會把讀失敗當作「文庫裏沒有」。
- 導入前記錄 pending，併發進程加鎖；響應成功後仍回讀新 key 才報告成功。
- 超時、客戶端中斷或部分導入後會阻止盲目重發；
import-status只覈對結果，不再次發送。
安全導入寫入個人文庫當前選中的分類；操作前應確認目標分類，過程中避免在 Zotero UI 裏切換分類。已有條目的分類不會自動改變，已有副本也不會自動合併或刪除。鎖只協調同一本地 API 地址與同一狀態目錄下的本插件進程，無法阻止其他軟件或原生 UI 同時導入。升級插件時保留狀態目錄；待覈查結果不能靠改 session 或清記錄自動重試。更細說明見倉庫內 skills/zotero/references/import-reliability.md 與 docs/import-hardening.md。
適用場景與注意¶
適合誰
- 已在日常使用 Zotero Desktop，並開啓本地 API 的研究者或開發者。
- 希望在 DSH 對話裏直接搜文庫、讀已索引全文、導入 RIS、導出 BibTeX，而不想每次手工複製元數據的人。
需要注意
- DSH 生態理念是「一切皆插件」；SkillHub 等目錄是社區站點，與 DeepSeek / 幻方無官方從屬關係，不要把它當成官方應用商店。
- 插件不替代 Zotero 本身的 PDF 閱讀與附件管理；索引缺失時全文能力會受限。
- 安裝即信任維護者代碼在本機進程內執行；請閱讀 GitHub 源碼與許可證後再安裝。
結尾¶
dsh-zotero 把 Zotero Desktop 的搜索、索引全文、導入導出接到 DSH 的 zotero 技能上，適合在本機已有文庫的前提下做文獻向對話。安裝命令、版本約束與導入行爲以倉庫 README 爲準。
- 社區目錄頁：https://www.skillhub.cn/plugins/chanhaoxian5-ship-it/dsh-zotero
- 源碼與文檔：https://github.com/chanhaoxian5-ship-it/dsh-zotero
