dsa-zotero-sidebar

✨ 功能一览

• 🗂️ 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 半改动时需要重启）。

指定 profile / 装完自动重启（可选）

# 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 件事（全部幂等，可安全重复执行）：

1. 上游依赖自检：若该 profile 未装 dsh-better-sidebar（本插件的宿主），先执行它的官方一键安装；
2. 预写 allowBuilds（规避 pnpm 11 的构建脚本拦截）；
3. 预写 minimumReleaseAgeExclude，放行「发布不足 24 小时」的新版本；
4. 执行 dsh plugin --profile <profile> add dsa-zotero-sidebar：登记依赖 → 识别包内 dsh.bundle.patch → 自动注册进 dsh.profile.bundles 挂载；
5. 清理旧版残留的手动挂载行，避免「双挂载」（页面出现两个 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 扩展点