前言¶

在 DSH 的插件化工作流裏，一個常見缺口是把分散的文獻管理、PDF 解析、全文筆記和 Agent 檢索串成同一條鏈路：Zotero 裏有題錄，PDF 原文需要解析，Agent 回答又需要可追溯引用。已有做法通常要手動導出、單獨跑解析腳本，再人工整理 wiki。dsh-zotero-wiki 針對這個流程提供一套 DSH 插件與 CLI。

這是什麼¶

dsh-zotero-wiki 是一個 DeepSeekHarness（dsh）× Zotero 插件，由 Wechsels 維護，許可證爲 MIT。它自動同步 Zotero 文獻庫，用 MinerU 解析 PDF、用 DeepSeek 閱讀全文，把文獻編譯成可檢索的 Obsidian Wiki，並讓 Agent 在回答時附帶可追溯的文獻引用。

它同時面向兩類使用方式：在 DSH 會話裏調用原生工具，以及用 CLI 執行同步、解析、編譯、LINT 和遷移。

核心功能¶

• 雙源同步：支持本地 zotero.sqlite 只讀副本，或 Zotero Web API 增量同步。
• 交互式範圍選擇：可選擇全部、指定 Collection（含子級）或標籤過濾，選擇結果持久化。
• PDF 解析：通過 MinerU 官方開放平臺上傳、輪詢、下載 Zip，解析產物寫入 raw/ bundle。
• DeepSeek 全文筆記：使用 deepseek-chat 閱讀全文，並生成中文結構化筆記。
• 優雅降級：無 PDF 或解析失敗時，基於標題和摘要生成簡版筆記，後續可升級。
• 解析配額與併發：默認單輪最多 50 篇，併發 3，失敗可下輪重跑。
• 解析預覽：parse_zotero_wiki 無參數調用只返回候選統計與樣本，不觸發 MinerU 調用。
• Wiki 編譯：生成主題綜述、index/authors/years 索引、交叉鏈接、歸檔標記與追加式 log。
• LINT 自檢：檢查索引一致性、內部鏈接、raw 引用、圖片鏈接與孤兒圖，並支持 auto-fix。
• 查詢歸檔：archive_zotero_query 可將問答歸檔爲 wiki 歸檔頁，並更新 index 與 log。
• Agent 查詢：使用 minisearch 內存全文檢索與中文 bigram 分詞，返回片段與 [Zotero key, §章節] 引用。

安裝與啓用¶

環境要求是 Node.js ≥ 22.19，使用內置 node:sqlite。同步階段需要 Zotero 本地庫或 Web API Key；parse 階段需要 MinerU Token 與 DeepSeek API Key。

配置存放在 .env。首次運行任意 CLI 命令時，若缺少必要配置，會自動彈出交互式配置嚮導；可用 --no-wizard 跳過。

本地目錄準備完成後，可用下面命令把插件註冊到 dsh：

npx -y @deepseek-ai/dsh plugin --profile web add file:/path/to/dsh-zotero-wiki

其中 file:/path/to/dsh-zotero-wiki 需要替換爲本地實際路徑。註冊後，可以在 CLI 中執行工作流，也可以在 dsh 工具中調用同步、解析、查詢和歸檔接口。

典型用法¶

CLI¶

下面的命令用於同步、解析、編譯、自檢和遷移。先同步題錄，再預覽待解析候選，確認後執行解析與編譯。

node dist/cli.js sync

增量同步；首次會彈出交互式範圍選擇並持久化。

node dist/cli.js parse --dry-run

預覽待解析候選，約等於預覽模式且零外部調用。

如需限定解析範圍，可用以下參數：

node dist/cli.js parse --topic T
node dist/cli.js parse --collection C
node dist/cli.js parse --keys K1,K2
node dist/cli.js parse --limit N

分別按主題、Collection、Zotero key 或篇數上限限定解析。

node dist/cli.js compile

生成綜述、索引、交叉鏈接與歸檔標記，並自動 LINT。

node dist/cli.js compile --no-review

跳過 LLM 綜述。

node dist/cli.js lint
node dist/cli.js lint --report-only

執行 LINT 檢查並 auto-fix，或僅報告。

node dist/cli.js migrate
node dist/cli.js migrate --apply

對舊 wiki 單篇頁做遷移 dry-run，或應用遷移。

dsh 工具¶

Agent 側可調用以下原生工具：

query_zotero_wiki(query, topic?, max_results?)

檢索 Wiki，並返回片段、元數據與引用。

sync_zotero_wiki()

手動增量同步並重建查詢索引。

parse_zotero_wiki(topic?, collection?, keys?, limit?)

無參數時返回候選預覽；帶參數時執行解析與筆記生成。

archive_zotero_query(title, body, topic?, source_keys?)

把查詢回答歸檔爲 wiki 歸檔頁。

同步邊界與限制¶

• 未歸入任何 Collection 的文獻會跳過。
• Zotero 中刪除條目時，插件不會物理刪除筆記，而是標記 status: archived；恢復後自動復原。
• 解析默認受配額控制：單輪最多 50 篇，併發 3。
• 明確不做：向量數據庫、自動聚類、多用戶服務端、定時後臺服務、Web UI、Zotero 註釋同步、引用頁碼提取。

適用場景與注意¶

適合有 Zotero 文獻庫，並希望把 PDF 原文、全文筆記、Obsidian Wiki 和 Agent 查詢放在同一工作流中的使用者。它更適合單人或本地工作流：配置本地路徑、API Key，並按需運行 CLI 或 dsh 工具。

使用前需要確認本地環境滿足 Node.js ≥ 22.19，並準備好 Zotero 訪問方式、MinerU Token 與 DeepSeek API Key。插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。許可證爲 MIT。

結尾¶

dsh-zotero-wiki 的價值在於把“同步、解析、筆記、編譯、檢索、引用”放在同一條可運行鏈路裏，而不是隻做一個文獻索引工具。

GitHub：https://github.com/Wechsels/dsh-zotero-wiki

目錄頁線索（該 URL 來自插件線索，已抓取資料中未出現，本文不把它當作確定事實）：https://www.skillhub.cn/plugins/Wechsels/dsh-zotero-wiki