Skip to content

DSH 插件(四):让 Agent 查你的笔记和真实论文 ​

让模型“介绍一下 Transformer 的原始论文”,它能说出标题、作者、年份,甚至给你一个 DOI。你去查,DOI 是编的。

这不是模型不努力,是这件事本来就不该由它做。检索和引用是确定性的,应该交给代码;模型只负责读懂之后解释。

vault-memory 和 academic-paper 分别处理两类证据:你自己的笔记,和公开文献。这篇讲它们怎么把“查”这件事从模型手里拿走。

一、私有证据:把 Obsidian 库变成可检索的索引 ​

vault-memory 不把笔记塞进上下文,而是先建本地索引:

  1. 扫描配置的 vault 目录,跳过 .obsidian、忽略规则命中的文件和超大文件;
  2. 解析 frontmatter、标题、标签和正文,生成一份纯文本;
  3. 写入本地 SQLite,正文进 FTS5 虚表;
  4. 可选调用 Ollama 的 bge-m3 生成向量,存进同一库。

检索时先走 FTS5,语法或状态异常就退回 LIKE:

js
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 之后、工具指引之前:

js
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:

数据源接口拿到的信息
arXivAtom XML标题、作者、摘要、发布日期、DOI、PDF
Semantic ScholarGraph API引用数、期刊、DOI、CorpusId

两边都查时,结果要合并去重。去重键按优先级取:

js
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-memoryacademic-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 是怎么接上的。

本文阅读--次|全站访问--次|访客--人