zotero-citation

name	zotero-citation
description	Zotero 文献引用工作流助手。通过 Zotero 本地 API 读取文献库，为用户指定的文字段落或论文全文自动匹配参考文献，生成规范格式的 Reference。当用户需要"引用文献"、"分配参考文献"、"从 Zotero 选文献"、"生成 Reference 列表"、"匹配引用位置"、"添加参考文献"、"给这段话配引用"、"帮我找合适的参考文献"时触发。也适用于查询 Zotero 文献库、获取文献元数据、或管理论文 citation 的场景。
allowed-tools	Read, Edit, Bash, Write, Glob, Grep
model	opus

Zotero 文献引用工作流

核心功能

从 Zotero 本地文献库中检索文献，为用户提供的任意文字段落或论文全文智能匹配参考文献，生成规范格式的 Reference。

使用模式

本 skill 支持两种使用模式，根据用户输入自动判断：

模式 A：段落级匹配（用户提供特定段落）

用户直接粘贴一段或多段文字，为其中的论点匹配合适的参考文献。

工作流：

1. 分析段落中的每个论点/声明
2. 从 Zotero 候选文献中匹配
3. 输出：标注了引用位置的段落 + Reference 条目

模式 B：全文匹配（用户指定论文文件）

读取整篇论文，逐段分析并分配参考文献。

工作流：

1. 读取论文文件（⚠️ 先确认版本）
2. 逐段提取论点并匹配
3. 输出：引用位置表 + 完整 Reference 列表

---

前置条件

1. Zotero Desktop 必须运行
2. 本地 API 已启用：Zotero → 编辑 → 设置 → 高级 → 允许其他应用程序通过 API 访问

验证连接：

curl -s "http://localhost:23119/api/users/0/items?limit=1"

⚠️ URL 必须加引号，否则 zsh 会因 ? 报 no matches found 错误。

支持文件

• Zotero API 端点与查询详情：见 references/zotero-api-reference.md

---

工作流程

步骤 1：确认输入与环境

1. 判断使用模式：
   • 用户直接给出了文字段落 → 模式 A
   • 用户指定了论文文件或说"全文" → 模式 B（需确认文件版本）
2. 验证 Zotero 本地 API 连接
3. 确认目标 Collection（文献分类），询问用户从哪个 Zotero 分类中选取候选文献

步骤 2：获取候选文献

获取 Collection 结构并拉取候选文献列表。

curl -s "http://localhost:23119/api/users/{USER_ID}/collections" | python3 -c "
import json, sys
data = json.load(sys.stdin)
for c in data:
    print(f\"{c['key']}: {c['data']['name']} (parent: {c['data'].get('parentCollection', 'none')})\")"

⚠️ 子分类文献需单独查询，父分类 API 不自动返回子分类条目。

获取条目时必须过滤 itemType 为 attachment 和 note 的条目。

详细 API 调用见 references/zotero-api-reference.md。

步骤 3：文献-文本匹配

分析目标文本（段落或全文），提取每个需要引用支撑的论点，然后与候选文献摘要进行语义匹配。

深度阅读：当用户要求精读某篇特定文献时，通过本地路径提取 PDF 全文：

1. 查询附件 key：GET /api/users/{ID}/items/{ITEM_KEY}/children（筛选 itemType=attachment）
2. 用 pdftotext 提取全文：

pdftotext ~/Zotero/storage/{ATTACHMENT_KEY}/文件名.pdf -

仅在用户明确要求时使用，常规匹配只需摘要即可。

匹配原则：

文本内容类型	匹配文献类型
背景/综述性论点	survey / tutorial 类
具体技术声明（如 "RAG enhances..."）	该技术代表性论文
概念定义（如 "Agentic AI augments..."）	定义该概念的论文
方法论论点（如 "LLM reward shaping"）	提出该方法的论文
应用场景描述	与场景最匹配的论文
数据/结论引用（如 "studies show..."）	提供该数据的原始论文

匹配质量检查：

• 每个引用必须有明确的支撑关系，不做"凑数"引用
• 全文模式下，检查引用分布均匀性，避免全集中在 Introduction
• 同一论点可配多篇文献（如 [1]-[3]），但需各有侧重

步骤 4：确认输出格式

在生成输出前，询问用户两个问题：

1. 引用格式：默认 IEEE，可选 APA、GB/T 7714、Chicago 等
2. 输出形式：
   • Reference 文本（默认）：直接可粘贴的参考文献列表
   • BibTeX 条目：.bib 格式，适用于 LaTeX 工作流

如用户未指定，默认输出 IEEE 格式的 Reference 文本。

步骤 5：生成输出

IEEE Reference 格式模板

期刊文章：

[N] A. B. Author1, C. D. Author2, and E. F. Author3, "Title," Journal Name, vol. X, no. Y, pp. XX–YY, Mon. Year.

预印本：

[N] A. B. Author1 et al., "Title," arXiv preprint arXiv:XXXX.XXXXX, Mon. Year.

会议论文：

[N] A. B. Author1 and C. D. Author2, "Title," in Proc. Conference Name, City, Country, Year, pp. XX–YY.

格式要点：

• 超过 3 位作者用 "et al."
• 期刊名使用标准缩写（IEEE 缩写表见 reference 文件）
• 页码用 en-dash（–）而非连字符（-）

BibTeX 格式模板

@article{AuthorYear,
  author    = {Author1, A. B. and Author2, C. D.},
  title     = {Title of Article},
  journal   = {Journal Name},
  volume    = {X},
  number    = {Y},
  pages     = {XX--YY},
  year      = {2024},
  doi       = {10.xxxx/xxxxx}
}

BibTeX 的 cite key 使用 第一作者姓+年份 格式（如 Wang2024），重名时加后缀 a/b/c。

⚠️ Zotero API 也支持直接导出 BibTeX：在 API 请求中添加 format=bibtex 参数。

模式 A 输出（段落级）

直接在用户段落中标注引用位置，并附上对应的 Reference / BibTeX 条目：

原文标注：
"...多模态架构普遍采用视觉-文本特征序列拼接的统一接口机制 [1], [2]。"

Reference:
[1] A. Author, "Title...," Journal, ...
[2] B. Author, "Title...," Journal, ...

模式 B 输出（全文级）

1. 引用位置表：

编号	文献简称	引用位置	引用理由
[1]	Author2024	Sec. I, 第2段	支撑XXX论点

2. 完整 Reference 列表（或 BibTeX 文件内容）

---

常见问题

问题	解决方案
zsh 报 no matches found	URL 加双引号
查不到子分类文献	单独用子分类 key 查询
读错论文版本	先 glob **/*.tex **/*.docx 列出所有版本让用户确认
混入 PDF 附件	过滤 itemType 非 attachment/note
需要 BibTeX	可手动组装或用 API format=bibtex 直接导出