DSH 插件(四):让 Agent 查你的笔记和真实论文
让模型“介绍一下 Transformer 的原始论文”,它能说出标题、作者、年份,甚至给你一个 DOI。你去查,DOI 是编的。
这不是模型不努力,是这件事本来就不该由它做。检索和引用是确定性的,应该交给代码;模型只负责读懂之后解释。
vault-memory 和 academic-paper 分别处理两类证据:你自己的笔记,和公开文献。这篇讲它们怎么把“查”这件事从模型手里拿走。
一、私有证据:把 Obsidian 库变成可检索的索引
vault-memory 不把笔记塞进上下文,而是先建本地索引:
- 扫描配置的 vault 目录,跳过
.obsidian、忽略规则命中的文件和超大文件; - 解析 frontmatter、标题、标签和正文,生成一份纯文本;
- 写入本地 SQLite,正文进 FTS5 虚表;
- 可选调用 Ollama 的
bge-m3生成向量,存进同一库。
检索时先走 FTS5,语法或状态异常就退回 LIKE:
try {
raw = store.searchFts(ftsQuery, limit * 3)
} catch {
raw = []
}
if (raw.length === 0) raw = store.searchLike(qs, limit * 3)这个兜底不是“保险起见”。FTS5 对查询串很挑,用户输入带引号、冒号或中文标点时,MATCH 可能直接抛语法错误。没有兜底,搜索会表现为“偶尔什么都搜不到”。
为什么不用 FTS5 自带的 snippet
FTS5 有 snippet() 和 highlight(),但这里没用。原因是中文分词用的是 bigram:查询“记忆注入”会被切成 记忆、忆注、注入,FTS5 的高亮按 token 走,返回的片段经常从词中间切开。
所以片段是在原文上自己截的:先找完整查询串,找不到再找任一长度 ≥2 的 token,以命中位置为基准开窗,前后加省略号。代码只有二十多行,但比调 FTS5 的参数更可控。
注入:不是每次对话都重算
索引建好后,插件通过 ctx.systemPrompt.section() 注册一段动态文本,位置在 persona 之后、工具指引之前:
ctx.systemPrompt.section({
name: "vault-memory:user-memory",
order: 60,
text: () => {
if (!ready()) return ""
const body = renderMemoryMarkdown(distillVaults(vaults), maxChars)
return body ? `${HEADER}\n\n${body}` : ""
},
})三个细节:
- 返回空串就不渲染,没配置 vault 或索引没就绪时不会塞一段空标题;
- 函数型 text 每次组装求值,静态字符串在部分 preset 下不生效;
- 先等索引就绪再蒸馏,否则插件刚加载时永远注入空内容。
结果有 TTL 缓存,默认 10 分钟;注入上限默认 1,200 token。这两个值都是防“记忆层把上下文吃满”。
踩坑:vaultKeys 每项必须带 index 引用
最初的实现只存了路径,蒸馏时再去查索引,结果永远是空注入。原因是后台全扫还没完成,路径能拿到,索引对象还没挂上去。后来把 { path, index } 一起放进 vaultKeys,并在注入前短轮询等 index.ready,问题才消失。
写入只有一个入口
vault_capture 是唯一会改 vault 的工具。它先返回预览,用户确认后才落盘,默认写进 Captures 目录,并带上来源标签。巡检工具只给建议,不自动改笔记——知识库是用户的,插件不能替用户做整理决定。
二、公开证据:两个数据源,一套引用
academic-paper 提供 7 个工具:检索、详情、引用、库增 / 查 / 删 / 导出。数据源只有两个公开 API:
| 数据源 | 接口 | 拿到的信息 |
|---|---|---|
| arXiv | Atom XML | 标题、作者、摘要、发布日期、DOI、PDF |
| Semantic Scholar | Graph API | 引用数、期刊、DOI、CorpusId |
两边都查时,结果要合并去重。去重键按优先级取:
const key = paper.arxivId
? `arxiv:${paper.arxivId.toLowerCase()}`
: paper.doi
? `doi:${paper.doi.toLowerCase()}`
: `title:${normalizeTitle(paper.title)}`arXiv 优先,因为它的 ID 最稳定;没有 ID 才退到 DOI;连 DOI 都没有,才用归一化标题。顺序反过来会把同一篇论文留成两条。
引用格式不交给模型
GB/T 7714、APA、BibTeX 三种格式全部由本地函数生成,模型只传论文标识和格式名。几个必须处理的边界:
- 作者超过 3 人,GB/T 7714 取前 3 加“等”;APA 超过 20 人取前 19 加省略号;
- 中文姓名不拆“姓 名”,整体作为姓氏;
- 缺年份写“出版年不详”或
(n.d.),不能编一个; - BibTeX 的 key 由“姓氏 + 年份 + 题名首词”生成,并转义 LaTeX 特殊字符。
这些规则写进代码后,同一篇论文每次生成的引用完全一致。模型参与格式化,就会有“这次多个句号、下次少个作者”的随机性。
那个 undefined 引发的输出校验错误
工具返回的 Paper 对象里有不少可选字段。数据源没给时,映射函数会显式赋 undefined。DSH 的工具输出要求“无损 JSON”,快照校验不允许 undefined 叶子,于是报:
value is not lossless JSON修法是在工具输出边界做一次清理,把值为 undefined 的键删掉,内部存储保持原样。这类错误跟业务逻辑无关,但会让一个已经跑通的工具在返回阶段失败。
三、两个插件的共同原则
| 问题 | vault-memory | academic-paper |
|---|---|---|
| 证据从哪来 | 本地 Obsidian 库 | arXiv / Semantic Scholar |
| 检索方式 | FTS5 主 + LIKE 兜底 + 可选向量 | 远程 API + 双源去重 |
| 模型负责 | 理解与归纳 | 理解与综述 |
| 代码负责 | 索引、检索、写入 | 检索、去重、引用格式 |
| 失败时 | 返回空注入,不阻塞会话 | 返回明确错误,不编造 |
一句话:能让代码确定的,就不要让模型生成。
为什么不直接给模型一个 web_search
通用搜索返回的是网页片段,不是结构化文献元数据;标题、作者、DOI 都可能缺,模型只能补全,补全就是幻觉的来源。专用 API 加确定性解析,拿到的字段是完整的,缺字段时也能明确说缺。
四、边界
vault-memory 的检索质量取决于笔记本身:没有标题、没有标签、正文很短的笔记,FTS5 和向量都救不了。它也没有做跨库去重,同一个主题分散在多个 vault 里,需要用户自己整理。
academic-paper 只覆盖 arXiv 和 Semantic Scholar,中文文献(知网、万方)需要账号鉴权,没做。它也不下载全文 PDF,只提供元数据和公开摘要。
下一篇换到开发日常:一个扫描 TODO 的插件,为什么需要 8 个工具和一个侧边面板,以及 host 与 client 之间那层 HTTP 是怎么接上的。