Analyze Paper

Zotero Literature Note 初始化 Skill

用户提供一个 citekey，本 skill 完成以下工作：

1. 从 Zotero 本地 API 获取文献元数据和 PDF 本地路径
2. 用 MinerU 将 PDF 解析为 Markdown 全文
3. AI 深度阅读全文并生成结构化分析
4. 将分析内容追加写入 Obsidian vault 中可读文件名的 literature note

前置检查（执行前自动完成，任一失败则报错退出）

• VAULT_ROOT：从当前工作目录向上逐级查找，首个同时包含 .obsidian/、notes/literature/、attachments/zotero_convert/ 的目录即为 vault 根目录；推断失败则提示用户手动指定
• Zotero API：curl -s http://localhost:23119/api 返回正常；若不通，则终止当前skill执行
• MinerU 环境：必须能运行 mineru（或本机实际配置的 MinerU 可执行文件），且所需模型已安装/可用。若 MinerU 命令、模型或运行环境不可用，立即报错退出；不得改用 pdftext 或其他纯文本解析方案继续执行。

执行步骤

Step 1：从 Zotero API 获取元数据

运行脚本，路径为 skill 目录下的 scripts/fetch_zotero_item.py（即 <SKILL_DIR>/scripts/fetch_zotero_item.py），传入 citekey：

python <SKILL_DIR>/scripts/fetch_zotero_item.py --citekey <citekey>

返回 JSON，包含：

• citekey, title, authors, year, journal, abstract, doi
• tags：Zotero 中的标签列表
• pdf_path：PDF 文件的本地绝对路径
• annotations：Zotero 内置高亮与批注

如果 citekey 未找到，报错退出，提示用户在 Zotero 中刷新 citekey。

如果 pdf_path 为空，报错退出，提示用户检查 Attanger 配置。

如果 pdf_path 不为空但文件不存在：

1. 先尝试自动修正：Windows 不允许文件夹名以 . 结尾，Attanger 会去掉末尾的点（如 Meng et al. → Meng et al）。将路径中每个组件末尾的 . 去掉后重试。
2. 若修正后仍不存在，报错退出，提示用户在 Zotero 中右键 → Manage Attachments → Rename and Move。

Step 2：解析 PDF 全文

输出目录固定为 <VAULT_ROOT>/attachments/zotero_convert/<citekey>/。

必须记录本次 PDF 转换方式，并写入 literature note frontmatter：

pdf_conversion_method: "mineru"
pdf_conversion_has_images: false  # MinerU 输出中存在可引用图片时为 true

如果沿用已有转换结果，必须检查转换目录内容来判断来源：

• 只有 <citekey>.md 或纯文本 Markdown，且没有图片文件：视为旧的 pdftext 结果，不得沿用；必须删除或忽略该结果并重新用 MinerU 转换。
• MinerU 输出通常包含结构化 Markdown 和图片资源目录/图片文件：仅在能够确认来源为 MinerU 时才可沿用，并设置 pdf_conversion_method: "mineru"；若存在图片，设置 pdf_conversion_has_images: true。
• 判断不确定时，不要猜测或写 unknown；必须重新运行 MinerU。若 MinerU 环境不可用或转换失败，立即报错退出，不进入 Step 3。

MinerU（唯一允许方案）

布局检测 + 公式识别 + 表格提取，输出结构化 Markdown，但在 CPU 机器上极慢（本机 i5-10210U 实测 25+ 分钟/18页）：

MINERU_MODEL_SOURCE=modelscope \
`mineru` 或本机实际存在的 MinerU 可执行文件 \
  -p <pdf_path> -o <output_dir> -b pipeline -m txt -l en

MinerU 3.0.4，模型缓存位置依本机 MinerU 配置而定 首次使用须提前运行：MINERU_MODEL_SOURCE=modelscope mineru-models-download -s modelscope -m pipeline

执行前必须先确认 MinerU 环境存在。若 mineru --help 或本机配置的等价命令无法运行、模型缺失、依赖缺失、GPU/CPU 环境无法完成转换，必须报错并停止当前 skill；不得回退到 pdftext。

使用 MinerU 时，必须检查输出中的图片文件。若存在图片：

• 根据论文内容选择足够数量的代表图，不设固定上限。优先覆盖核心思想、方法/模型架构、算法流程、关键实验设置、主要结果、对比结果或消融结果；若两张图不足以支撑读者理解方法和结论，应选择更多。
• 不要为凑数量附图。每张被嵌入的图都必须提供独立信息，避免重复、装饰性或与分析正文关系弱的图片。
• 将图片嵌入最相关的 AI-generated section 中，优先放在 方法论摘要 或 实验与结果。
• 不要直接嵌入 MinerU 原始图片路径。MinerU 路径通常包含长论文标题、空格或非 ASCII 字符，在 Windows + Obsidian 中容易渲染失败。
• 先把选中的代表图复制到短路径：<VAULT_ROOT>/attachments/literature_figures/<citekey>/<short-ascii-name>.jpg。文件名使用短 ASCII kebab-case，例如 figure-04-pac-fea-net.jpg。
• 在 literature note 中使用从实际 note 文件（位于 notes/literature/，文件名为可读格式）到图片文件的相对 Markdown 图片链接：![简短图名](../../attachments/literature_figures/<citekey>/<short-ascii-name>.jpg)。若 note 不在 notes/literature/，必须重新计算相对路径。
• 每张图片后必须写清楚：
  • 这张图代表什么；
  • 图中关键部件/曲线/子图分别是什么；
  • 它传达的核心信息是什么；
  • 它如何支撑本文的方法或实验结论。
• 不要只写“见图”或“该图展示结果”；图像说明必须足够详细，让读者不打开原文也能理解图的意义。

Note 文件命名规则

Literature note 的文件名不得使用 citekey。citekey 只作为 frontmatter 字段保留，用于和 Zotero/BBT 稳定关联。

笔记路径使用：

<VAULT_ROOT>/notes/literature/<first-author-surname> <year> <full-title>.md

命名规则：

• first-author-surname：取第一作者姓氏，首字母大写；作者字段为 Surname, Given 时取逗号前内容；作者列表为 Given Surname, Given Surname 或单个作者为 Given Surname 时，取第一个作者片段的最后一个词。
• year：优先使用 Zotero 返回的 year；若为空，从 citekey 末尾提取 4 位年份；仍为空时使用 n.d.。
• full-title：使用 Zotero 返回的完整标题，不要改成 citekey 缩写。
• Windows 文件名非法字符 <>:"/\|?* 必须替换为空格或短横线；合并连续空格，去掉文件名末尾的空格和句点。
• 生成或更新 note 时必须保留 frontmatter 中的 citekey 字段。

定位已有 note 时，不要假设文件名等于 citekey。应先在 notes/literature/ 中按 frontmatter citekey 查找；找不到时才检查是否存在旧的 citekey 文件名。若发现旧 citekey 文件名，应重命名为上述可读格式，并同步更新 vault 内指向旧文件名的 Obsidian 链接。

Step 3：AI 深度分析全文

这是本 skill 的核心步骤。将 MinerU 输出的全文 Markdown 作为输入，按以下框架逐一提炼：

3.1 全文概括

• 用通俗的大白话解释，这篇论文要解决什么问题？
• 现有方法的哪些不足促使了本工作？
• 问题的规模和难度如何界定？
• 核心方法是什么？用一句话概括

3.2 核心贡献

列出 2-4 个真正的创新点，每个附上：

• 创新的具体内容
• 为什么这个创新重要
• 实验中如何验证了这个创新的有效性

3.3 方法论摘要

这一节必须写成“从零开始讲清楚”的教学型解释，不要只列论文术语或公式。默认读者没有该领域背景，但愿意认真读懂方法。

写作顺序必须遵守：

• 先解释基础概念：在进入论文方法前，先解释理解该方法所需的基本概念。每个概念都要回答“它是什么、为什么需要它、在本文中扮演什么角色”。例如 FEM、网格、节点、自由度、裂纹尖端、应力强度因子、富集函数、partition of unity 等；具体概念随论文主题调整。
• 再解释问题设置：用普通语言说明输入是什么、要求解什么、传统方法卡在哪里。
• 再讲方法流程：按原文逻辑逐步解释，每一步都要说明“做什么、为什么这么做、这一步解决了什么困难、输出给下一步什么”。不要只写“不超过 5 步”的摘要；必要时写 6-10 个小步骤也可以。
• 最后给公式：公式必须在直觉解释之后出现。公式前先用文字解释每个符号的含义；公式后再用一句话说明它在算法中的作用。保留关键 LaTeX，但不要让公式替代解释。
• 补充实现细节：包括节点/自由度如何选择、积分或离散化如何处理、结果量如何计算、方法与传统方法的本质区别。

质量要求：

• 用中文解释时，优先用短句和具体类比，避免直接堆英文术语。
• 对专业术语首次出现时给出括号内英文，之后可使用简称。
• 如果论文方法依赖图示或流程图，用文字重建图的含义，不要只说“见 Figure X”。
• 方法论部分应足够详细，让没有背景的读者能复述方法的主要思想和执行流程。

3.4 实验与结果

• 使用了哪些数据集？规模和特点？
• 对比的 baseline 方法有哪些？
• 核心指标的数值结果（保留关键数字；实验结果可以是数值型，用表格呈现）
• 消融实验揭示了什么？

3.5 局限性与批判

• 作者自己承认的局限性
• 从方法设计角度可以质疑的地方
• 实验设置上的潜在不足
• 结论是否过度外推？

3.6 综合评价

对以下维度各给出 1-10 分并附简短理由：

• 创新性：方法本身是否有实质性新意
• 技术质量：理论推导和实现是否严谨
• 实验充分性：实验是否足够支撑结论
• 写作质量：论文表达是否清晰
• 领域影响：对所在领域的潜在价值

3.7 与已有文献的关联

根据 Zotero tags 和论文内容，判断：

• 与 vault 中哪些已有笔记相关（链接目标使用 literature note 的可读文件名，例如 [[Bahmani 2024 Discovering interpretable elastoplasticity models via the neural polynomial method enabled symbolic regressions]]；不要使用 citekey 作为链接目标）
• 属于哪个研究方向/技术路线
• 是否引用了 vault 中已有的论文

3.8 Key Concepts

提炼本文涉及的关键概念（术语、方法名、理论框架等），每个概念给出一句话定义：

• 若 vault 中已有对应的 key concept 笔记，用 [[concept-note-name]] 格式链接，建立文档间的关联
• 若尚无对应笔记，记录概念名称和定义，为后续整理 key concept note 做准备

3.9 Tags 整合

从三个来源合并生成最终 tags 列表，写入笔记 frontmatter 的 tags 字段：

来源 1：Zotero tags（Step 1 已获取）

• 直接使用 fetch_zotero_item.py 返回的 tags 列表，原样保留

来源 2：PDF 关键词

• 在全文 Markdown 中搜索 Keywords、Key words、Index Terms 等字段，提取作者列出的关键词
• 规范化处理：去除特殊符号、统一小写、多词短语保留原样（如 lattice spring model）

来源 3：AI 生成 tags

• 根据全文内容，生成 8-15 个补充 tags，覆盖以下维度：
  • 研究方法：本文使用的核心算法/模型名称（如 VCPM, lattice spring model）
  • 研究问题：本文解决的核心问题（如 fracture anisotropy, crack propagation）
  • 应用领域：涉及的工程/物理领域（如 computational mechanics, fracture mechanics）
  • 技术分类：方法论层面的分类（如 particle method, non-local model, discrete method）
  • 关联方向：与已有范式的关系（如 peridynamics, meshfree method）
• 格式：英文小写，空格用连字符（如 crack-branching）或保留原术语大小写（如 VCPM）

合并规则：

1. 三来源去重合并
2. 最终 tags 数量目标：15-25 个
3. 保留 Zotero tags 原始格式不变；PDF keywords 和 AI tags 统一为英文小写

Step 4：写入 Obsidian literature note

笔记格式严格遵照 templates/zotero-note.md 模板书写，不得自行调整结构或顺序。

frontmatter 必须包含 PDF 转换信息：

• pdf_conversion_method: 固定写 "mineru"
• pdf_conversion_has_images: true 或 false

若模板尚未包含这些字段，也要在创建或更新 note 时补入，放在 citekey 或 tags 字段附近即可。

写入策略：

• 按 frontmatter citekey 在 notes/literature/ 中定位已有 note；找不到时再检查是否存在旧的 citekey 文件名
• 若文件不存在：按模板从零创建完整笔记，文件名使用 first-author-surname year full-title.md，填入 Zotero API 元数据及 AI 分析内容
• 若文件已存在：找到 <!-- AI_GENERATED_START --> 和 <!-- AI_GENERATED_END --> 标记，只替换标记之间的内容；已存在的 section（基本信息、摘要、我的笔记、高亮与批注等）不重新生成，保持原样不变
• 若文件名仍是 citekey：先重命名为可读文件名，再更新 vault 内所有指向旧文件名的 Obsidian 链接

错误处理

脚本说明

脚本位于 <SKILL_DIR>/scripts/ 目录：

• fetch_zotero_item.py — 从 Zotero API 获取元数据和 PDF 路径