English: README.en.md
zotnote 是一个面向科研文献管理的 Agent Skill（DeepSeek Harness / Claude Code 等兼容 SKILL.md 的智能体通用）：从你的 Zotero 文库中挑选指定文章，自动提取 PDF 的章节结构与全部图表（含题注），生成图文并茂、逐节精读、带 YAML frontmatter 的 Markdown 笔记，并按 Zotero 文库目录结构镜像写入 Obsidian Vault，直接接入知识图谱与文献关系网络。
Zotero 条目 ──▶ PDF（本地 storage 优先）──▶ 章节/图表提取 ──▶ Obsidian 精读笔记
zotero.mjs extract_pdf.py vault.mjs / run.mjs
下图是 Obsidian 中一篇精读笔记的真实效果截图：
⚠️ 注意：上面截图只是完整笔记的一个片段（速览/归纳部分），仅用于快速展示 整体观感。该笔记的完整效果（逐节精读、全部图表详解、LaTeX 公式、关联笔记等） 请点击浏览完整笔记文档：📄 查看完整笔记 demo.md（以本仓库 的 PRO-GAN 论文精读笔记为例）。
完整笔记同样接入 Obsidian 知识图谱，下图是新笔记在 Obsidian 图谱视图中的真实关系网络效果：
- 选择即读：按文章标题/作者/关键词搜索 Zotero 条目，一条命令完成全流程
- 批量增量（新！）：
batch.mjs --collection <目录>处理整个 Zotero 文库目录下的所有文章，自动跳过已经建过笔记的（按 Vault 笔记 frontmatteritem-key判定，改名/移动笔记不误判），幂等可断点续跑，配--recursive递归子目录、--limit分批 - workflow 精读编排（v0.5.0 新！）：
prepare-workflow.mjs+tools/notes-workflow.js（DSH workflow 脚本）——批量骨架的并行精读层，每篇一个 subagent，schema 强校验 +check-note.mjs内容级自检（占位符/$ 配对/图解说/status），失败自动重试，wikilink 由预扫描的 Vault 标题清单保证篇间一致。实测 8 篇一次 8/8 通过 - 图文并茂：自动定位并裁剪每张图/表（题注感知），位图走嵌入图、矢量图走绘图包围盒，含 300dpi 高清导出与
crop手工补图子命令 - 逐节精读模板：每个 § 预留「主要内容 / 科学问题 / 方法 / 特征性质结论 / 研究价值 / 关键公式」；每张图预留「图表内容 / 图内解说 / 科学内涵」三段解说，原题注自动引用
- 图文随章节（v0.6.0 新）：图/表按 PDF 页码自动映射到所属章节，解说直接嵌在对应 § 下（含"涉及图表"索引行），阅读时图文对照无需翻页；未识别归属的图集中文末兜底区，可手动归位
- 自然语言与学术规范（v0.3.0 新）：撰写时强制成段叙述、学术用词、术语一致、逻辑衔接、忠实原文（SKILL.md §7.1），杜绝占位注释与口语化表述
- LaTeX 公式（v0.3.0 新）：关键公式以行内
$…$/ 行间$$…$$写入，交付前按 §7.3 自查清单校验渲染（美元配对、单位转义、希腊字母命令）；vault.mjs自动提示$配对异常 - 知识图谱就绪：YAML frontmatter（title/authors/year/journal/doi/zotero 双链接/collections/tags/status）+
[[wikilink]]关联区 - 目录镜像：
<Vault>/Zotero Notes/<collection 逐级路径>/<短标题 年份>/，与 Zotero 分类树一一对应；图片进assets/<itemKey>/ - 安全写入：永不覆盖已有笔记（同名自动加日期后缀）；本地 PDF 离线可用
pip install pymupdf # 图/文提取 (必要)
# Node.js >= 22 (脚本运行时, 无需 npm install)编辑 ~/.config/zotnote/config.json（Windows: C:\Users\<你>\.config\zotnote\config.json）：
{
"installDir": "<本仓库绝对路径>",
"zotero": {
"apiKey": "你的ZoteroAPIkey",
"userID": 123456,
"storagePath": "E:/software/Zotero/Zotero/storage"
},
"obsidian": {
"vaultRoot": "C:/Users/你/Documents/Obsidian Vault",
"notesRoot": "Zotero Notes"
},
"pythonCmd": "python"
}- API key：https://www.zotero.org/settings/keys 创建（阅读权限即可）
storagePath：Zotero「设置→高级→数据目录」下的storage子目录； 留空则走 Zotero Web API 下载 PDF- 验证：
node scripts/zotero.mjs --mode verify
# ① 找条目
node scripts/zotero.mjs --mode search --query "white-light flare"
# ② 一键生成笔记骨架（--dry-run 先预览）
node scripts/run.mjs --key MYBFJAXP
# ③ 批量增量：处理某个文库目录的全部文章, 自动跳过已有笔记的
node scripts/batch.mjs --collection "works" --recursive --dry-run # 先预览
node scripts/batch.mjs --collection "works" --recursive --limit 5 # 每次处理5篇随后打开笔记，把 <!-- … --> 占位符替换为你的精读内容即可。
| 文件 | 职责 |
|---|---|
SKILL.md |
Agent 技能指令（触发词：Zotero 精读/论文阅读笔记/图文笔记/Obsidian 知识图谱） |
scripts/zotero.mjs |
Zotero Web API 客户端：搜索 / info / tree / pdf（本地优先下载兜底） |
scripts/extract_pdf.py |
PyMuPDF 提取器：章节标题识别（字号+编号+词表，去伪标题）、图/表题注定位、位图/矢量图裁剪、crop 手工子命令 |
scripts/vault.mjs |
Obsidian 写入器：目录镜像、图片拷贝、YAML frontmatter + 精读模板骨架、防覆盖 |
scripts/run.mjs |
一键流水线编排 |
scripts/batch.mjs |
批量增量：整库目录处理，自动跳过已有笔记（按 frontmatter item-key），产出 manifest |
- 章节：按文本块字号聚类 +
^\d+(\.\d+)*编号模式 + 标准章节词表 （Abstract/Introduction/Methods/Results/…）三重判定；1.与标题分离排版 自动合并；过滤时间戳、坐标刻度、机构地址、图内(a)/(b)标注等伪标题。 - 图/表：正则匹配
Figure/Table/图/表 N题注块 → ① 同栏上方嵌入图 （横向并排/纵向堆叠 panel 自动合并）→ ② 矢量图用页内get_drawings()包围盒 → ③ 兜底取题注上方文本间隙。200dpi 默认导出，--dpi可调。 - 笔记：frontmatter 携带 zotero://select + zotero.org 双链接，
collections镜像 Zotero 分类链；正文按用户五问模板组织 （解决了什么问题 / 方法 / 特征性质 / 研究价值 / 未来方向与前沿关联）。
Obsidian Vault/
└── Zotero Notes/
└── works/
└── 2025_Spectropolarimetry/
└── Stokes Inversion ...
├── Stokes Inversion ....md ← 精读笔记
└── assets/
└── ABCD1234/
├── figure-1-p3.png
├── figure-2-p5.png
└── table-1-p7.png
- 题注位置特殊/图裁坏了 →
python scripts/extract_pdf.py crop <pdf> --out x.png --page 21 --rect "x0,y0,x1,y1" --dpi 300 - 没有 Zotero 本地安装 →
storagePath留空，走网络下载 - 笔记页面布局不同 →
--notes-relative-root/--assets参数可改 - 与 arxiv-checkup 的关系 → complementary：arxiv-checkup 入库，zotnote 精读
MIT © 2026 gychen-NJU
如果这个 skill 对你有帮助，欢迎 ⭐ 收藏与 PR！