Zotero 文献引用 yuzh2001/dsh-zotero

dsa-zotero-sidebar

在 DeepSeek Harness 里直接浏览、引用你的 Zotero 文献库 Zotero 文件树 双击引用 内联搜索 /zotero 命令 模型工具右侧边栏 + 输入框快捷引用，边读论文边写提示词。
基于 dsh-better-sidebar 的右侧栏，宿主侧直接读 Zotero SQLite

🌏 中文

✨ 功能一览

- 🗂️ Zotero 文件树：在 better-sidebar 右侧栏渲染你的 Zotero 文库（收藏夹层级、懒加载展开），宿主直接读本地 zotero.sqlite，无需 API key
- 🖱️ 双击引用：双击任意论文/文件夹 → 在输入框注入可读引用 《论文题名》{%ZoteroItem:key%}，光标零破坏（纯文本，不用 DSH chip 占位）
- 🔎 & 内联搜索：在输入框打 & 弹出自绘搜索层（真 input、自动聚焦），按标题/作者搜库、方向键或回车选择，选中即插入引用
- ⌘ /zotero 命令：斜杠命令打开同一个搜索层，交互与 & 完全一致
- 🛠️ 模型工具：注册 resolve_zotero_ref，模型看到 {%ZoteroItem:key%} 即可解析该论文的标题/作者/年份/摘要在库路径
- 🔗 Zotero 深链：悬停引用可跳转 zotero://select/items/... 在本地点开原文

🚀 安装

前置：已装好 DSH（dsh web 能正常运行）、部署了 dsh-better-sidebar、Node.js ≥ 20、pnpm ≥ 10，且本机装有 Zotero 桌面端（读取 %LOCALAPPDATA%/Zotero/ 或 ~/Zotero/ 下的 zotero.sqlite）。

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/yuzh2001/dsh-zotero/main/scripts/install.sh | bash

Windows（PowerShell 5.1+ / pwsh）：

irm https://raw.githubusercontent.com/yuzh2001/dsh-zotero/main/scripts/install.ps1 | iex

装完硬刷新浏览器（Cmd/Ctrl+Shift+R）即可看到右侧栏的 Zotero 标签页（client 改动无需重启 DSH；仅 host 半改动时需要重启）。

指定配置档 / 装完自动重启（可选）

macOS / Linux：安装到指定 profile ext-dev，装完重启
curl -fsSL https://raw.githubusercontent.com/yuzh2001/dsh-zotero/main/scripts/install.sh | bash -s ext-dev --restart

Windows PowerShell
& ([scriptblock]::Create((irm 'https://raw.githubusercontent.com/yuzh2001/dsh-zotero/main/scripts/install.ps1'))) -Profile ext-dev -Restart

不确定的话，可先加 --dry-run（PowerShell 用 -DryRun）预览步骤再执行。

手动安装（逐步命令，想看清每一步）

与一键脚本等价。第 ③ 步可重复执行；①② 只需做一次。

macOS / Linux（bash）：

cd ~/.dsh/profiles/web # 换成你的目标 profile

① 放行构建脚本（pnpm 11 拦截）
pnpm approve-builds --all

② 放行新版本（一次性；若已有该键，把 - dsa-zotero-sidebar 并入其下即可）
echo -e "\nminimumReleaseAgeExclude:\n - dsa-zotero-sidebar" >> pnpm-workspace.yaml

③ 安装并自动挂载（识别 dsh.bundle.patch，登记进 dsh.profile.bundles）
npx -y --package @deepseek-ai/dsh dsh plugin --profile web add dsa-zotero-sidebar

脚本内部做了什么（技术细节）

一键脚本自动完成 5 件事（全部幂等，可安全重复执行）：

0. 上游依赖自检：若该配置档未装 dsh-better-sidebar（本插件的宿主），先执行它的官方一键安装；
1. 预写 allowBuilds（规避 pnpm 11 的构建脚本拦截）；
2. 预写 minimumReleaseAgeExclude，放行「发布不足 24 小时」的新版本；
3. 执行 dsh plugin --profile <profile> add dsa-zotero-sidebar：登记依赖 → 识别包内 dsh.bundle.patch → 自动注册进 dsh.profile.bundles 挂载；
4. 清理旧版残留的手动挂载行，避免「双挂载」（页面出现两个 Zotero 标签）。
curl | bash / irm | iex 会执行远程代码——脚本已随仓库开源（scripts/install.sh / scripts/install.ps1），可先下载审阅。插件以 npm 包 dsa-zotero-sidebar@0.1.0 发布，通过 dsh.bundle.patch（随包的 cordis.patch.yml）由官方 CLI 自动挂载，不修改 DSH 源码。

更新

dsh plugin --profile web add dsa-zotero-sidebar

或重跑一次一键脚本；也可把 ~/.dsh/profiles/web/package.json 里的版本号改高后 pnpm install。改完硬刷新浏览器（Cmd/Ctrl+Shift+R）即可（client 改动无需重启 DSH）。

常见问题

| 现象 | 原因与解决 |
| 右侧栏没有「Zotero」标签 | 需要先装好 dsh-better-sidebar；本插件挂在它提供的右侧栏上。 |
| 搜不到论文 | 宿主在 %LOCALAPPDATA%/Zotero/zotero.sqlite（Win）或 ~/Zotero/zotero.sqlite（mac/Linux）找库；改过自定义 data dir 的话，用 DSH_ZOTERO_DIR 环境变量指过去。 |
| 报 Ignored build scripts | pnpm 11 拦截构建脚本。跑 pnpm approve-builds --all（一键脚本已自动处理）。 |
| 页面出现两个 Zotero 标签 | 双挂载：cordis.patch.yml 还留着旧的手动挂载行，删掉那段 - insert: ... zotero-sidebar ...（一键脚本会自动清）。 |

从源码安装 / 开发（可选）

git clone https://github.com/yuzh2001/dsh-zotero.git ~/Dev/dsh-zotero
cd ~/Dev/dsh-zotero && pnpm install && pnpm build
把 ~/.dsh/profiles/<profile>/package.json 的 dependencies 写 "dsa-zotero-sidebar": "link:~/Dev/dsh-zotero" 或直接 dsh plugin --profile <profile> add /path/to/dsa-zotero-sidebar.tgz

更新：git pull && pnpm install && pnpm build → 硬刷新（client 热加载；host 半改动才需重启）。

🔌 接入：作为 better-sidebar 的客户端

本插件通过 ctx.betterSidebar.registerTab 注册 id: 'dsa-zotero:library' 的 Zotero 标签页，与 better-sidebar 内置的 Explorer 等 tab 平级。

🛠️ 开发与构建

pnpm install
pnpm typecheck # tsc --noEmit
pnpm bundle # tsdown → lib/index.js + lib/client.js + lib/types

架构：单 npm 包、host/client 双半结构——host（src/index.ts）：/zotero/api JSON 路由（library.tree / node.expand / search / item.resolve），直读本地 zotero.sqlite（node:sqlite），受 Host 头信任围栏保护；client（src/client/index.tsx）：better-sidebar 的 Zotero 标签页 + &//zotero 引用浮层 + 背景懒加载。引用是纯文本 token 《题名》{%ZoteroItem:key%}，不走 DSH 的 chip/occurrence 占位，因此光标永远对齐、不破坏输入。

⚠️ 已知限制

- 需要本机装着 Zotero（读它的 SQLite），不支持只读 Zotero Web API
- 双击/搜索引用插入的是题名字面 + key 的纯文本，不改写原库

🔗 友情链接

- dsh-better-sidebar：本插件的右侧栏宿主
- DSH-better-sidebar 提供 ctx.betterSidebar.registerTab 扩展点