dsh-refkeeper
v0.1.5
Published
Verify and export the references your AI conversation already cited: BibTeX/RIS with evidence-anchored annotations.
Maintainers
Readme
dsh-refkeeper
English · 简体中文
长篇研究对话中的引文常散落在不同轮次、工具结果和摘要里。dsh-refkeeper 会从你选定的对话中提取引用,用五个学术注册表核对元数据,再整理为可追溯的文献条目并支持注解及 BibTeX/RIS 导出。注册表明确不一致的条目会留在隔离区,不会被当成已核实文献。

如果这个插件帮你省了时间,欢迎在 GitHub 上点个 Star,它能帮其他人找到这个插件。遇到 Bug 或想加功能,直接开 Issue 就行,中文英文都可以。每条都会看,有价值的会排进 Roadmap。
目录
功能 · 支持的标识符 · 支持的引用格式 · 为什么不自己复制 · 安装 · 使用 · 输出示例 · 判定规则 · 数据与隐私 · 开发 · 更新记录 · 许可证
功能
- 收集引用。范围可以是本轮、前 N 轮或整个对话。识别 DOI、arXiv 编号、PMID、PMCID、ISBN、报告号,也识别按 APA、GB/T 7714、IEEE、BibTeX、Vancouver 格式写出的参考文献行。部分历史 arXiv 分类编号(如
math.GT/0309136、cs/0112017)同样支持。 - 对照注册表核对。只有标题匹配、年份相差不超过一年、第一作者匹配,并且至少有一个注册表返回了记录,条目才会被接受。注册表有五个:Crossref、OpenAlex、arXiv、DataCite,加上 PubMed。
- 生成注解。捕获后,由当前会话使用的模型为每条写四个字段:摘要、与本书稿的关系、一段原文引证、注意事项。引证如果没在对话里逐字出现,会被丢弃。
- 导出。BibTeX、RIS 或两者。导出范围可以是最近一次捕获、你勾选的条目,或整个文献库。PMID 与 PMCID 会一起写进去。
- 说清存到哪里。捕获完成后,面板会告诉你这次存了多少条、存在工作区的
refs/refs.json;下面那个「导出到」是.bib/.ris的输出目录,不是文献库。
支持的标识符
| 标识符 | 格式示例 |
| --- | --- |
| DOI | 10.1002/joc.1688;https://doi.org/10.1002/joc.1688 |
| arXiv | 2401.01234、arXiv:2401.01234v2、https://arxiv.org/abs/2401.01234v2;旧式 math.GT/0309136、arXiv:math.GT/0309136v2 |
| 带标识符的链接 | https://arxiv.org/format/2401.01234、https://doi.org/10.1002/joc.1688、https://www.biorxiv.org/content/10.1101/2020.01.01.123456 |
| PubMed | PMID: 12345678;PMCID: PMC1234567 |
| ISBN | ISBN-10 0-306-40615-2;ISBN-13 978-0-306-40615-7 |
| 报告号 | NUREG-1234;PB123456;NACA 1234;NTRS 123456;AD-A123456;DOE/BR-123456;NASA/TM-2020-12345;EPA-600/R-14/001;RFC-9110 |
PMID 和 PMCID 必须带标签。没有标签的 6–8 位数字(如 20240101)会被忽略,避免误识别日期或样本号。PMCID 会先经 PMC 交叉解析,再查询 PubMed。
支持的引用格式
以整行文字贴进来的引用(而不是标识符)同样能被解析。
| 格式 | 示例 |
| --- | --- |
| APA | Smith, J. (2020). A study of something. Journal of Testing, 12(3), 45-67. |
| GB/T 7714 | 张三, 李四. 一种标题很长的中文文献标题测试用例[J]. 某某学报, 2020, 12(3): 45-67. |
| IEEE | [1] A. Smith, "A titled paper," Journal of Testing, vol. 12, no. 3, pp. 45-67, 2020. |
| BibTeX | @article{key, title = {A Study}, author = {Smith, John}, year = {2020}, doi = {10.1000/x}} |
| Vancouver | 1. Smith J, Doe A. A study of something. Journal of Testing. 2020;12(3):45-67. |
BibTeX 条目可以一次贴很多条 —— 一段消息里的几个块会被读成几条引用。
@string 宏会被展开,花括号会配对,所以 title = {A {DNA}-based method}
会作为一条完整的题名进来;没有题名的条目会被跳过,不会存成空条目。
标准号不是文献。ISO 9001、GB/T 12345、RFC 1918 只被当成文本,不会成为
条目 —— 研究对话里提到它们的次数远多于引用它们的次数。真正的报告号
(NACA 1234、NTRS 123456、DOE/BR-123456、NASA/TM-2020-12345、
RFC-9110)则会。
只有一个按钮
界面上只多了一样东西:输入框工具行里的 ❝ 引用,就排在「工作区内修改」和模型选择器旁边。没有侧栏、没有工具栏、没有常驻浮层。点一下才在窗口右上角展开捕获面板,关掉就恢复原样。

为什么不自己复制
三篇文献,手动复制就好。多了以后容易出错:一个 DOI 在工具结果里,一条 APA 在摘要里,还有一篇是两轮前只提过名字的。
让模型直接生成 .bib 更快,但模型会编页码、DOI 和作者顺序,这类错误往往到投稿前才被发现。
| | 手动复制 | 让模型生成 .bib | 本插件 |
| --- | --- | --- | --- |
| 条目从哪来 | 自己往回翻 | 模型的记忆 | 从你选定的对话里解析 |
| 元数据是否核对 | 没有 | 没有 | Crossref、OpenAlex、arXiv、DataCite、PubMed |
| 核对不通过时 | 无 | 照样保留 | 移入 refs/quarantine.json,不参与导出 |
| 编造的页码、DOI、作者 | 无 | 可能出现 | 字段取自注册表记录;无依据的字段留空 |
| 为什么稿子里有这篇 | 丢失 | 丢失 | 注解加一句原文引证 |
| 同一份库导出两次 | 无 | 不保证一致 | 字节相同;条目排序、citekey 稳定 |
| 没有引用过的文献 | 不会带入 | 会被带入 | 默认排除;工具输出不算引用 |
安装
在 DSH 打开设置 → 插件 → 添加插件,输入 dsh-refkeeper。这个包已发布到 npm,一步装好,不跑构建(tarball 里带 lib/)。在当前 profile 启用后重载。
想跟随仓库更新而不是锁定发布版,就在同一个输入框里填 Git 地址 https://github.com/ymwang92/dsh-refkeeper;仓库里也提交了 lib/,同样不需要构建。
配置
无需单独的插件 API key 或注册表配置;注解使用当前会话所选模型。面板中的「导出到」路径保存在 refs/settings.json,必须位于当前会话工作区内;文献库仍固定在 refs/refs.json。
使用
- 打开引用过文献的那个对话,点开输入框上方的捕获面板。
- 选择范围,点捕获文献。
- 面板会列出哪些已入库、哪些进了 ⚠ 隔离区。取消勾选这次不需要的条目。
- 选择 BibTeX 和/或 RIS,点导出本次捕获。
同样的事情用命令:
/refs capture --scope=all --save
/refs export --format=both文件写在会话工作区的 refs/ 目录下。要导出到别处,在面板里粘贴一次文件夹路径即可,之后记在 refs/settings.json 里。会话工作区之外的文件夹会被拒绝,因为宿主只允许写入工作区内。
输出示例
refs/annotated.md 是给人看的版本:
### Physiographically sensitive mapping of temperature and precipitation across the conterminous United States
- Daly, C.; Halbleib, M.; Smith, J. I. et al. · 2008 · International Journal of Climatology 28 15 2031-2064 · DOI [10.1002/joc.1688](https://doi.org/10.1002/joc.1688)
- verification: **verified** 3/3 · crossref, openalex
> **Summary** — PRISM 插值:基于台站数据并做地形调整,生成美国本土的气温与降水格点。
> **Why it matters** — 第 3 节 800 m 气候常年值所用的数据集。
> **Evidence** — "we use the PRISM 800 m normals (Daly et al., 2008) as the baseline for the downscaling."对应的 BibTeX 条目:
@article{daly2008physiographically,
author = {Daly, C. and Halbleib, M. and Smith, J. I. and Gibson, W. P. and Doggett, M. K.},
title = {Physiographically sensitive mapping of temperature and precipitation across the conterminous United States},
journal = {International Journal of Climatology},
year = {2008},
volume = {28},
number = {15},
pages = {2031--2064},
publisher = {Wiley},
doi = {10.1002/joc.1688},
url = {https://doi.org/10.1002/joc.1688},
abstract = {PRISM interpolation: temperature and precipitation grids ...}
}对话里没写卷、期、页码、出版社或语言时,这些字段从注册表记录补齐。对话和注册表都没有依据的字段不写进文件。
判定规则
对话文本
│ 标识符:DOI、arXiv 编号、带标签的 PMID/PMCID、ISBN、报告号
│ 参考文献行:APA、GB/T 7714、IEEE、BibTeX、Vancouver
▼
候选条目 ──► Crossref、OpenAlex、arXiv、DataCite、PubMed
(尽可能并发查询;PMCID 先经 PMC 交叉解析)
│
├─ 接受条件:标题匹配 · 年份相差 ±1 · 第一作者匹配
│ 且至少一个注册表返回记录
├─ 接受 ──► refs/refs.json (verified)
└─ 拒绝 ──► refs/quarantine.json (⚠,保留可见,默认不导出)还有第三种状态 unverified,用于注册表连不上的情况:条目留在库里,之后可以重试。网络故障不能说明引文有错。quarantined 则是注册表有应答、但结论不一致。
注解
四个字段:summary、relevance、evidence、caveats。捕获后由当前 profile 的默认模型根据提到这篇文献的对话行生成。提示词和解析层都拒绝描述「信息缺失」的句子(例如「摘录未提及本文」),这类内容存为空字符串,导出时整个字段省略,因此 BibTeX 里不会出现空的 note,RIS 里不会出现空的 N1。
模型调用每次捕获一次,上限 60 秒,最多覆盖 12 条。超出预算的条目、或当前没有可用模型的捕获,只保留书目字段,捕获结果会说明跳过注解的原因。ref_save 工具仍然接受你自己写的注解,已有的用户注解不会被覆盖。
中文文献
GB/T 7714 格式的参考文献行与 APA、IEEE、BibTeX、Vancouver 一起解析。中文标题按字符二元组与注册表记录比对(Dice ≥ 0.90),而不是按词元,否则罗马化的记录永远对不上。language 字段会写进两种导出格式。
中文期刊在开放注册表里的元数据很少。CNKI、万方、维普的链接只用于提取标识符,不作为注册表查询。中文条目需要手工修正的地方会比有英文 DOI 的文献多。
面板

| 控件 | 作用 |
| --- | --- |
| 范围 | 本轮、前 N 轮、整个对话 |
| 捕获文献 | 捕获、核对、生成注解并入库;结果列出保存了哪些、哪些进了隔离区 |
| 存储位置 | 列表上方那行说明这次存了多少条、存在工作区的 refs/refs.json |
| 每条前的复选框 | 决定下一次导出包含哪些条目;已入库的默认勾选,⚠ 的默认不勾 |
| 徽章 | 一眼看出这条的状态:已入表、⚠ 隔离、跳过、失败 |
| 副行 | 第一作者 · 年份 · 出版物,以及没通过时的那句原因 |
| 点条目 | 打开独立的编辑页,不挤在列表里 |
| 编辑页的三组字段 | 标识信息(条目类型、DOI、arXiv ID、PMID、PMCID、URL)、书目信息、出版信息 |
| 条目类型 | 七种类型的下拉框;自由文本会在导出时静默失败 |
| 手动入表 | 跳过的条目可以在这里补全元数据后入库 |
| 导出格式 | BibTeX、RIS 或两者 |
| 导出到 | .bib/.ris 的输出目录;留空表示 refs/exports/ |
| 导出本次捕获 | 写出勾选的条目 |
| 导出全部文献 | 写出整个文献库 |
列表自己会滚:面板是固定的头尾加中间滚动的一列,文献再多,导出按钮也一直够得着。
点开一条是独立的编辑页,字段按标识、书目、出版分成三组:

命令
| 要做的事 | 命令 |
| --- | --- |
| 先看对话里引用了什么,不写入 | /refs capture --scope=all --dry-run |
| 捕获并入库 | /refs capture --scope=lastN --turns=5 --save |
| 核对一条 | /refs verify --doi=10.1002/joc.1688 |
| 查看文献库 | /refs list [--quarantine] |
| 补齐卷、页码、出版社 | /refs enrich [--quarantine] |
| 提升已核验的隔离条目 | /refs promote [--ids=<payload>] 或 /refs promote --manual --reason=<text> |
| 修改一个字段 | /refs edit --id=<id> --payload=<base64url(json)> |
| 删除条目 | /refs remove <id\|doi\|arxiv>... 或 /refs remove --all --yes |
| 导出 | /refs export [--format=bibtex\|ris\|both] [--all] [--ids=...] [--out=path] |
| 设置导出文件夹 | /refs dir --set=<base64url(path)> 或 /refs dir --clear |
/refs 查看捕获状态
/refs capture [--scope=turn|lastN|all] [--turns=N] [--save] [--dry-run] [--include-tools]
/refs verify --doi=... | --arxiv=... | --title=... [--json]
/refs save --json='{...}'
/refs list [--limit=N] [--quarantine]
/refs edit --id=<id> --payload=<base64url(json)>
/refs enrich [--quarantine]
/refs promote [--ids=<payload>] [--manual --reason=<text>]
/refs remove <id|doi|arxiv>... [--quarantine]
/refs remove --all --yes [--quarantine]
/refs export [--format=bibtex|ris|both] [--out=path] [--include-quarantine]
/refs export [--ids=id,id] [--choose-dir] [--all]
/refs dir [--set=<base64url(path)>|--clear]/refs promote 会通过实时注册表重新核验隔离区条目,只迁移状态为 verified 的条目。--ids 把范围收窄到面板里勾选的那几条,隔离行上的两个按钮就是发它:重新核验 走实时校验,人工确认入表 直接迁入并记下 manual 状态与理由。若迁入的条目主表里已有同一条,会用新结果替换旧行,而不是留下旧记录。
不带 --save 时,/refs capture 只预览候选。导出默认只导最近一次捕获,加 --all
导出整个库。较长的 id 用 base64url 传输,因为真实 id 里含空格、<>、; 和括号。
同一篇文献不会在两处各存一份:先因故障进隔离区、后来捕获成功的条目会按身份
(DOI、arXiv id、ISBN 或标题加年份)合并成一条;remove 与 edit 会同时作用于
两张表,避免旧副本在 --include-quarantine 导出时重新出现。
工具
| 工具 | 用途 |
| --- | --- |
| ref_capture | 从对话里收集候选文献 |
| ref_verify | 对照注册表核对一个标识符或标题 |
| ref_save | 保存一条文献,可附带自己写的注解 |
| ref_export | 为一个批次、一组勾选或整个库写出 BibTeX/RIS |
| ref_ping | 报告哪些宿主服务和注册表可用 |
文件
refs/refs.json 已接受的文献,含注解
refs/quarantine.json ⚠ 未通过核对的条目
refs/last-capture.json 最近一次捕获的结果,也是默认导出范围
refs/settings.json 记住的导出文件夹
refs/annotated.md 阅读版:记录、核对结论、注解
refs/exports/ 默认导出目录都是普通 JSON 和 Markdown,可以和稿子一起提交、一起对比。
限制
- 不能替代 Zotero。跨年份的个人文献库(PDF、样式、同步)该用 Zotero。这个插件管的是一篇稿子的引用,来源是一段对话。
- 不读 PDF。所有信息来自对话文本和注册表。
- 导出受宿主沙箱限制,只能写进会话工作区。
- 每次捕获会调用一次模型(上限 60 秒),最多为 12 条生成注解。
- 中文期刊的注册表元数据稀疏,见上文。
数据与隐私
- 只有核对请求会离开本机:标识符或标题发给 Crossref、OpenAlex、arXiv、DataCite、PubMed。
- 注解使用会话里已经配置的模型,插件本身不持有 API key。
- 没有埋点。文献库就是一个本地文件。
开发
npm ci
npm test # vitest
npm run typecheck
npm run build # 先用 tsdown 打包宿主,再打客户端 bundletsdown 会清空 lib/,所以客户端 bundle 要在它之后执行。需要 Node 22 或更高版本。
更新记录
每个版本改了什么、为什么改,记在 CHANGELOG.md。
许可
MIT,见 LICENSE。
