SuperAPI AI 工具集

obsidian-paper-vault

写作与研究

查看项目

更新于 10-15 16:51

技能介绍

用途:把一批研究 PDF 转成 Obsidian 双层库——文献笔记(每篇一条,模板化)与原子概念笔记(跨论文综合)。即使用户未提 Obsidian,只要是把论文 PDF 文件夹整理成笔记的场景也适用。

关系:与 /lit-sync 共用同一批文献与概念笔记文件夹,但入口相反,不可互相覆盖。lit-sync 从 Zotero 集合或 refs.bib 进入,以 citekey 为笔记键,拥有 manuscript/_src/refs.bib 与提取文本缓存,是书目骨架;本技能从 PDF 文件夹进入,以简短描述性标题为键,笔记是通读摘要。绝不覆盖已有笔记:若按标题、DOI 或 citekey 已存在,则报告并跳过。

第 0 步:确认库布局,不要假设。写入前确定三个路径:库根目录(由用户指定或取 $OBSIDIAN_VAULT,绝不猜测 home 路径)、文献笔记文件夹(默认 Literature/,若库中已有 02_research/논문/、Papers/、文献/ 等承担该角色则沿用现有布局)、概念笔记文件夹(默认 Concepts/,同样沿用已有)。韩国语库结构可选启用 references/locale/ko/note_templates.md。确认 PyMuPDF 可用:python3 -c "import fitz; print(fitz.version)",安装用 pip install PyMuPDF;文本提取缓存到 ~/.local/cache/paper-vault-texts/,除非用户另行指定。

第 1 步:任何批次都先预提取 PDF 文本:python3 "${CLAUDE_SKILL_DIR}/scripts/extract_pdfs.py" <pdf_folder> <text_cache_folder> [max_pages]。默认 12 页,覆盖多数论文的摘要到讨论部分。若笔记内容空泛,说明文本仅含摘要或 OCR 质量差,需增加页数重提或检查源 PDF。无可用文本的纯图像扫描件报告为 FAILED …(需要 OCR),不生成 .txt,需单独 OCR 或交互式阅读,绝不批量处理。绝不要把 PDF 路径交给子智能体:打不开文件的子智能体会用训练数据写出看似合理却含虚构数字的笔记,应传 .txt 路径。单篇交互可直读 PDF,批量不行。

第 2 步:并行子智能体写笔记。每批分给多个子智能体,每个只带少量论文(过多会降低质量),同智能体内按主题分组以便识别反复出现的概念。需向子智能体提供:分配到的文本路径与目标文件名、references/templates.md 中的模板原文、已存在的概念笔记列表、禁止虚构的约束;完整提示见 references/subagent-prompt.md。全部笔记须遵守:数字、作者、日期只取自提取文本,绝不来自模型知识;文本未陈述的写“提取文本中未说明”;![[filename.pdf]] 中精确保留 PDF 文件名(文本名 .txt 换成 .pdf,逐字符对应);frontmatter 字段名须与模板一致(Dataview 查询遇字段改名会返回空表格而非报错);使用 references/tag-vocabulary.md 中现有标签词汇,不新造顶层标签;笔记名用 3–5 个关键词概念,而非 PDF 全标题或 paper_001。格式不确定时参考 assets/example_paper_note.md。

批次验收闸门:抽查两条笔记与其文本文件核对(一个样本量、一个效应估计)。若任一数值在文本中不存在,停止该批次并报告,是否豁免由用户决定。

第 3 步:在库中维护 PAPER_QUEUE.md,逐篇记录状态(done / pending / skipped / in progress),使 200 篇规模的库可跨会话推进,每批后更新。

第 4 步:文献笔记达到 10 条以上后抽取概念笔记。某短语在 3+ 条笔记中出现、有教学价值、且不同论文对其处理不同时,才值得建概念笔记;模型名、数据集、期刊属于实体而非概念。完整标准、频率扫描与 seedling/growing/mature 生命周期见 references/concept-extraction.md,格式见 assets/example_concept_note.md。每 5–7 条文献笔记产出约一条概念笔记为健康速度,更快即概念膨胀,会表现为大量用户从不编辑的存根笔记。概念笔记交付闸门:以 🌱Seedling 状态交付,定义标为占位符,须经用户审阅后才算读者自己的笔记,交接时须明确说明。

适用场景:科研文献批量整理、综述写作准备、Obsidian 知识库搭建。限制:依赖 PyMuPDF;纯扫描 PDF 无法处理;概念笔记数量与质量依赖用户审阅;与 /lit-sync 共存时职责边界须遵守,不得互相覆盖。