# Analyze Paper

> 初始化一篇文献的 Obsidian literature note。当用户提供 citekey 时触发此 skill。 流程：从 Zotero 本地 API 获取元数据和 PDF 路径 → 用 MinerU 解析 PDF 全文 → AI 深度分析全文 → 在已有基础卡片上追加完整分析内容。 触发词：/analyze-paper、citekey、初始化文献、分析论文、处理新文献、lit note、literature note init。

- Skill: `babyracoonbbq/analyze-paper` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add babyracoonbbq/analyze-paper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/babyracoonbbq/analyze-paper/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: BabyRacoonBBQ (https://skillmd.com/u/babyracoonbbq)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/babyracoonbbq/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：

```bash
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：

```yaml
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页）：

```bash
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 稳定关联。

笔记路径使用：

```text
<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 链接

---

## 错误处理

| 情况 | 处理方式 |
|---|---|
| citekey 在 Zotero 中找不到 | 报错，提示用户刷新 BBT citekey |
| PDF 路径不存在 | 报错，提示用户检查 Attanger 配置 |
| MinerU 环境不存在或模型不可用 | 报错，提示用户先安装并配置 MinerU；终止当前 skill，不进入 Step 3/Step 4 |
| MinerU 解析失败 | 报错，显示 MinerU 日志；终止当前 skill，不进入 Step 3/Step 4 |
| literature note 文件不存在 | 从 Zotero API 元数据从零创建完整笔记，文件名使用 `first-author-surname year full-title.md` |
| AI_GENERATED 标记不存在 | 提示用户更新模板，追加到文件末尾作为兜底 |

---

## 脚本说明

脚本位于 `<SKILL_DIR>/scripts/` 目录：
- `fetch_zotero_item.py` — 从 Zotero API 获取元数据和 PDF 路径