前言¶

在 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