English · 中文
dsh-zotero 是面向 DeepSeek Harness 的本地 Zotero 插件。Agent 在对话里检索、阅读、引用并按需修改文献库；你在文献面板里浏览整个库并复制引用；文献轨迹则集中展示 Agent 在当前会话中查到的文献、提取的原文片段与导出内容，方便对照核对。
所有操作均通过 Zotero 本地 API（`127.0.0.1:23119`）与桌面端交互，读取无需配置 API Key。
## 主要功能
- **对话检索**
- 检索与阅读：按标题、作者、年份或全文搜索文献，读取元数据、个人笔记与本地 PDF 全文。
- 原文片段定位：围绕具体问题从全文、批注和笔记中提取相关段落，PDF 批注附带原始页码。
- 引用与导出：按 CSL 样式生成行内引用或参考文献表，支持导出 BibTeX、RIS 与 CSL-JSON。
- 写入与扩展（可选）：开启后可创建笔记、修改标签与合集（每次均需会话审批）；启用学术检索组件后可跨 7 个外部索引检索文献并核验引用。
- **文献轨迹**
- 检索记录：会话顶部首屏显示每次调用的查询词、范围、筛选条件与命中数。
- 原文核对：按文献条目整理提取出的段落与批注，标明出处与原始页码，方便核对。
- 导出汇总：跨条目汇总当前会话生成的所有引用与 BibTeX，自动去重，可直接复制或下载。
- **文献面板**
- 全库浏览：在右侧边栏浏览合集树、标签、保存的搜索与回收站，支持多条件组合筛选。
- 详情与阅读：查看条目元数据、关联笔记与附件列表，支持在右侧阅读栏直接打开本地 PDF。
- 引用与联动：动作行直接复制 BibTeX、CSL 引用或条目信息；支持将选中文献一键填入对话输入框。
两个入口与三个组件的分工见[产品模型](docs/product-model.md)。
## 安装
从 npm 安装（推荐）：
```sh
dsh plugin --profile add dsh-zotero
```
从 GitHub 预构建分支安装：
```sh
dsh plugin --profile add github:Vncntvx/dsh-zotero#release
```
安装完成后新建会话即可使用。在插件管理器中打开 **dsh-zotero** 详情页，其配置区提供完整配置表单。
> 提示：从 `main` 源码分支直接安装需要本地执行构建。pnpm 默认拦截依赖构建，使用 `#release` 分支可免除构建配置直接安装。
## 前置条件
1. 安装并运行 Zotero 7 及以上桌面版（写入功能需 Zotero 10）。
2. 在 Zotero 中开启本地 API：**设置 → 高级 → 勾选“允许此计算机上的其他应用程序与 Zotero 通信”**。
## 使用示例
先检索，再核对：
```text
用户：帮我找 Risk 相关的论文
Agent → zotero_search(query: "Risk", itemTypes: ["journalArticle"])
返回 5 篇匹配结果；会话顶部的文献轨迹同步出现这 5 篇
用户：这篇里关于方法论的讨论，帮我找出来
Agent → zotero_retrieve(ref: "zotero://user/0/item/ABCD1234", query: "methodology",
sources: ["annotation", "fulltext"])
返回排序段落与来源标注（批注附带原始页码）
用户：把这三篇导出为 BibTeX
Agent → zotero_export(refs: [...], format: "bibtex")
生成 BibTeX 条目，可在文献轨迹的导出视图复制或下载
```
写论文时直接取用：在文献面板找到条目，动作行点「复制引用」或「复制 BibTeX」，把引用文本或词条粘贴到论文源文件中；需要 Agent 参与时点「提问」或「加入对话」，内容会预填进会话草稿。
## 工具一览
插件提供 8 个读取工具与 15 个写入工具。写入工具默认关闭，可在配置中开启 `writeEnabled`。
| 工具 | 用途 |
| ------------------- | ------------------------------------------------------------ |
| `zotero_search` | 按标题、作者、年份、标签或全文搜索文献，支持按分类与标签筛选 |
| `zotero_browse` | 浏览文献库结构，包括分类合集树、标签列表和保存的搜索 |
| `zotero_get` | 读取单篇文献的元数据详情、摘要、附件与笔记列表 |
| `zotero_children` | 查看文献关联的子条目，包括独立笔记、PDF 附件和阅读批注 |
| `zotero_retrieve` | 围绕问题从全文、笔记与批注中检索相关段落（批注保留页码） |
| `zotero_changes` | 检查文献库最近的新增、修改或删除记录 |
| `zotero_attachment` | 获取文献关联的本地 PDF 文件路径 |
| `zotero_export` | 生成格式化引用、参考文献列表，或导出 BibTeX、RIS、CSL JSON |
15 个写入工具（笔记、标签与合集归属、合集、条目、保存搜索、Trash 恢复、全库标签、批量操作）默认关闭，开启后仅写入个人库，且每次写入都需要审批。全部 23 个工具的完整契约见[工具参考](docs/tools.md)。
## 安全与隐私
- 插件只向本机 Zotero 接口发请求，不调用 Zotero 云端服务。外部请求只来自默认关闭的学术检索组件。
- 写入工具默认禁用。开启后每次修改文献库都会展示审批与计划审查卡，用户确认后才执行；写入不自动重试。
- 插件只解析和校验本地附件路径，不执行系统命令，也不启动后台常驻进程。
## 说明文档
### 使用
| 文档 | 内容 |
| ----------------------------------- | -------------------------------------------- |
| [快速入门](docs/getting-started.md) | 安装、连接验证与第一个任务 |
| [产品模型](docs/product-model.md) | 两个入口、三个概念、三个组件与四条边界 |
| [功能概览](docs/features.md) | 对话能力、文献轨迹、文献面板、写入与学术检索 |
| [故障排查](docs/troubleshooting.md) | 常见问题、诊断步骤与处理方法 |
### 维护
| 文档 | 内容 |
| --------------------------------- | -------------------------------------------------- |
| [系统架构](docs/architecture.md) | 数据流、分层职责、组件边界与设计边界 |
| [工具参考](docs/tools.md) | 23 个本地工具与 7 个学术工具的参数、返回值与错误码 |
| [配置参考](docs/configuration.md) | 各设置命名空间的字段、默认值与热更新机制 |
| [开发指南](docs/development.md) | 构建、测试、调试与发布流程 |
验收场景（[docs/scenarios.md](docs/scenarios.md)）供维护者使用。
## 许可证
[MIT](./LICENSE)
