Zotero 思源文献笔记

这个技能解决什么问题

Zotero 里的文献条目、PDF 附件和高亮标注是分散的，想把它们整理成思源笔记里结构化的文献笔记，传统做法要么手动复制导出，要么让 AI 在上下文里直接读论文全文——前者琐碎易错，后者随着 PDF 变长会迅速吃掉上下文，还容易漏掉格式规则。这个技能把这条链路拆成可编排的脚本步骤，让数据读取、格式转换和笔记写入各归其位。

核心能力与工作方式

数据读取层通过 Zotero 本地 API 工作：zotero-status 检查连接，zotero-item / zotero-items 拿条目元数据或搜索，zotero-notes 取 Zotero 内的笔记与 PDF 标注，zotero-attachment 解析出 PDF 附件的实际路径。前置条件是 Zotero 桌面端开启了 Allow local API，思源笔记处于运行状态。

转换层由 pdf-to-md 承担，它调用 MinerU（mineru-open-api，需先完成认证）把 PDF 解析为 Markdown，解析出的图表再通过 siyuan-upload-images 上传到思源并回填引用。

笔记生成层是一套严格的主 agent / 子 agent 分工：主 agent 负责读配置、调 Zotero API、跑 pdf-to-md、校验输出、最后调 lit-note-create 把笔记写入 litNote.notebookName 指定的笔记本；真正阅读论文 Markdown、分析全文并起草笔记正文的工作，必须交给专用的 zotero-note-writer 子 agent 完成。模板和格式规范放在子 agent 的 prompt 里，不进主 agent 上下文。笔记创建后还能用 lit-note-append 按 section 追加或替换内容，ask-supplement 支持基于 TODO 的问答式补充。

反向链接依赖四级 key 体系：itemKey 定位文献条目，pdfKey 对应 PDF 附件，annotationKey 精确到某条标注（L4），docId 是思源文档 ID。有了 annotationKey，笔记里的引用可以反向指回 PDF 的具体高亮位置。

适用边界与注意点

• itemKey 和 pdfKey 几乎总是不同的两个值，混用会导致链接指向错误的对象。
• lit-note-create 只接受 --content-file 传参。用 --content 直接把正文塞进 shell 命令行，$$ 会被展开成进程 ID，LaTeX 公式和反斜杠都会被破坏。
• 流程第一步（步骤 [0]）是读取 config.json 的 litNote.notebookName，为空就直接中止——目标笔记本不允许被脚本顺手覆盖。
• MinerU 是可选依赖：没有 PDF 附件时，技能可以仅基于 Zotero 元数据和已有笔记生成一份基础笔记；PDF 里没有任何标注时，反向链接降级为 L2/L3 级别，不会有标注级引用。
• 笔记已存在时不会静默覆盖，而是返回现有 docId，由用户决定打开阅读还是重建。