Study

强制规则（必须遵守）

只要用户输入不是 URL 且不是本地文件路径，就必须通过 Zotero Better-BibTeX JSON-RPC 搜索本地论文库。严禁使用 WebSearch / WebFetch / 任何网络搜索工具去 查找论文。paper-vault 的核心前提是用户想学习他们已经在 Zotero 里管理的论文。

如果 Zotero 查询失败（服务未启动、Better-BibTeX 未安装、搜索结果为空）， 必须停下来询问用户，不要自行改用 WebSearch 或编造 PDF 链接。

支持多种输入格式：

• 论文标题或关键词：在 Zotero 中搜索
• citation key（如 hafnerMasteringDiverseControl2025）：直接通过 Zotero 获取
• 本地路径：~/Downloads/paper.pdf
• URL：https://arxiv.org/abs/1706.03762

注意：当输入是标题/关键词时，不要猜测 arxiv URL 去下载——必须走 Zotero。

第 1a 步：判断输入类型

USER_INPUT="<user-input>"

if [[ "$USER_INPUT" =~ ^https?:// ]]; then
  # URL：下载 PDF
  INPUT_PATH=$(node ${CLAUDE_PLUGIN_ROOT}/skills/study/scripts/download-pdf.cjs "$USER_INPUT")
elif [[ -f "${USER_INPUT/#\~/$HOME}" ]]; then
  # 本地文件路径
  INPUT_PATH="${USER_INPUT/#\~/$HOME}"
else
  # 默认分支：只要不是 URL/本地路径就进入这里（标题、关键词或 citation key）
  # 必须通过 Zotero 查询，禁止使用 WebSearch/WebFetch。
  echo "Searching Zotero for: $USER_INPUT"

  SEARCH_RESULT=$(curl -s -f --max-time 5 "http://localhost:23119/better-bibtex/json-rpc" \
    -X POST -H "Content-Type: application/json" \
    -d "{\"jsonrpc\":\"2.0\",\"method\":\"item.search\",\"params\":[\"${USER_INPUT}\"],\"id\":1}")
  CURL_EXIT=$?

  echo "$SEARCH_RESULT"
  echo "curl exit code: $CURL_EXIT"
fi

Claude 必须按下述规则解析 SEARCH_RESULT 并处理异常情况：

1. Zotero 不可达（curl 返回非 0，或连接被拒绝）：
   • 告诉用户："Zotero 似乎没有运行，请启动 Zotero 并确认 Better-BibTeX 插件已安装。"
   • 停止工作流，不要改用 WebSearch。
2. 搜索结果为空（result 字段是空数组）：
   • 告诉用户："在 Zotero 中未找到与 <input> 匹配的论文。请提供更精确的标题/作者、 改用 URL（arxiv/DOI）或本地 PDF 路径。"
   • 停止工作流，不要自动退回到 WebSearch 或编造链接。
3. 只有一个匹配：直接取其 citation-key 作为 CITATION_KEY，进入 1b。
4. 多个匹配：向用户展示前若干候选（标题 + 作者 + 年份 + citation-key）， 请用户选择一个后再进入 1b。

第 1b 步：通过 citation key 获取 PDF 路径（Zotero 输入时）

此处使用的 CITATION_KEY 只能来自：(a) 用户直接输入的 citation key，或 (b) 1a 步 Zotero 搜索的结果。绝不能由 Claude 凭标题推断或来自 WebSearch。

CITATION_KEY="<citation-key-from-search>"

ATTACH_RESULT=$(curl -s "http://localhost:23119/better-bibtex/json-rpc" \
  -X POST -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"method\":\"item.attachments\",\"params\":[\"${CITATION_KEY}\"],\"id\":1}")

echo "$ATTACH_RESULT"
# 从返回结果中提取 path 字段（选择 .pdf 后缀的条目）
# INPUT_PATH="<extracted-pdf-path>"

第 1c 步：解析 PDF

node ${CLAUDE_PLUGIN_ROOT}/skills/study/scripts/parse-pdf.js "$INPUT_PATH"

输出内容包括：

• title、authors、abstract、full content、githubLinks、codeLinks

第 2 步：在生成材料前评估论文

在生成任何文件前，先评估：

1. 难度等级

   • Beginner
   • Intermediate
   • Advanced
   • Highly Theoretical

2. 论文类型

   • Theoretical
   • Architecture-based
   • Empirical-heavy
   • System design
   • Survey

3. 方法复杂度

   • Simple pipeline
   • Multi-stage training
   • Novel architecture
   • Heavy mathematical derivation

该评估决定：

• 是否创建 method.md
• 是否创建 .ipynb
• 解释深度
• 代码示例复杂度

第 2.5 步：精确生成 2 个语义标签（必做）

在生成文件前，基于对论文语义的理解推断出恰好 2 个标签。

规则：

• 必须生成且只生成 2 个标签
• 两个标签必须不同
• 每个标签应简短（1-3 个词）
• 避免泛化标签：paper、research、ai、ml
• 优先使用一个表示问题/领域的标签，以及一个表示方法/核心思想的标签

示例：

• machine translation, self-attention
• 3d detection, bev transformer
• protein folding, structure prediction

第 3 步：创建 Obsidian 笔记目录

OBSIDIAN_VAULT="$HOME/Documents/Obsidian Vault"
NOTE_DIR="$OBSIDIAN_VAULT/Paper-Vault/{paper-slug}"

mkdir -p "$NOTE_DIR"
mkdir -p "$NOTE_DIR/images"
mkdir -p "$NOTE_DIR/code"

所有后续文件均写入 $NOTE_DIR/。

第 4 步：生成核心学习材料

所有文件通过 Write tool 直接写入：

$HOME/Documents/Obsidian Vault/Paper-Vault/{paper-slug}/

必需文件

README.md

• 论文主题简介（一段）
• 难度等级
• 材料导航方式
• 关键收获
• 预计学习时间
• 文件夹结构概览

summary.md

• 背景上下文
• 问题定义
• 主要贡献
• 关键结果
• 定量指标

insights.md（最重要）

• 用通俗方式解释核心思想
• 为什么这个方法有效
• 它带来了什么概念上的转变
• 取舍
• 局限性
• 与先前工作的比较
• 实际意义

qa.md

15 个问题：

• 5 个基础问题
• 5 个中级问题
• 5 个高级问题

使用以下格式：

### Question

<details>
<summary>Answer</summary>

Detailed explanation.

</details>

---

条件生成文件

method.md（大多数论文建议生成）

包含：

• 组件拆解
• 算法流程
• 架构图（如有需要可用 ASCII）
• 分步骤解释
• 伪代码（兼顾解释）
• 实现陷阱
• 超参数敏感性
• 复现风险

mental-model.md（大多数论文建议生成）

• 这属于哪一类问题？
• 默认需要哪些先验知识？
• 它在更广泛研究版图中的位置
• 应该如何在脑中归类这项工作

reflection.md（可选自动生成）

• 如果我要扩展这篇论文
• 还有哪些开放问题
• 哪些假设比较脆弱
• 它在实际中可能在哪些地方失效

第 5 步：代码演示（必做）

至少创建一个可运行的演示，写入：

$HOME/Documents/Obsidian Vault/Paper-Vault/{paper-slug}/code/

指导原则：

• 自包含
• 可独立运行
• 带教学性注释（解释原因）
• 聚焦核心贡献
• 清晰性优先于完整性

可能的类型：

• 简化的概念实现
• 可视化脚本
• 最小架构演示
• 交互式笔记本（.ipynb）

命名要有描述性：

• model_demo.py
• vectorized_planning_demo.py
• contrastive_loss_visualization.ipynb

避免使用泛化文件名。

第 6 步：在 Obsidian 中打开笔记

obsidian vault="Obsidian Vault" open path="Paper-Vault/{paper-slug}/README.md" newtab