| 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：段落级匹配（用户提供特定段落）
用户直接粘贴一段或多段文字，为其中的论点匹配合适的参考文献。
工作流：
- 分析段落中的每个论点/声明
- 从 Zotero 候选文献中匹配
- 输出：标注了引用位置的段落 + Reference 条目
模式 B：全文匹配（用户指定论文文件）
读取整篇论文，逐段分析并分配参考文献。
工作流：
- 读取论文文件（⚠️ 先确认版本）
- 逐段提取论点并匹配
- 输出：引用位置表 + 完整 Reference 列表
前置条件
- Zotero Desktop 必须运行
- 本地 API 已启用：Zotero → 编辑 → 设置 → 高级 → 允许其他应用程序通过 API 访问
验证连接：
curl -s "http://localhost:23119/api/users/0/items?limit=1"
⚠️ URL 必须加引号，否则 zsh 会因 ? 报 no matches found 错误。
支持文件
工作流程
步骤 1：确认输入与环境
- 判断使用模式：
- 用户直接给出了文字段落 → 模式 A
- 用户指定了论文文件或说"全文" → 模式 B（需确认文件版本）
- 验证 Zotero 本地 API 连接
- 确认目标 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 全文：
- 查询附件 key：
GET /api/users/{ID}/items/{ITEM_KEY}/children（筛选 itemType=attachment）
- 用
pdftotext 提取全文：
pdftotext ~/Zotero/storage/{ATTACHMENT_KEY}/文件名.pdf -
仅在用户明确要求时使用，常规匹配只需摘要即可。
匹配原则：
| 文本内容类型 | 匹配文献类型 |
|---|
| 背景/综述性论点 | survey / tutorial 类 |
| 具体技术声明（如 "RAG enhances..."） | 该技术代表性论文 |
| 概念定义（如 "Agentic AI augments..."） | 定义该概念的论文 |
| 方法论论点（如 "LLM reward shaping"） | 提出该方法的论文 |
| 应用场景描述 | 与场景最匹配的论文 |
| 数据/结论引用（如 "studies show..."） | 提供该数据的原始论文 |
匹配质量检查：
- 每个引用必须有明确的支撑关系，不做"凑数"引用
- 全文模式下，检查引用分布均匀性，避免全集中在 Introduction
- 同一论点可配多篇文献（如 [1]-[3]），但需各有侧重
步骤 4：确认输出格式
在生成输出前，询问用户两个问题：
- 引用格式：默认 IEEE，可选 APA、GB/T 7714、Chicago 等
- 输出形式：
- 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] | Author2024 | Sec. I, 第2段 | 支撑XXX论点 |
- 完整 Reference 列表（或 BibTeX 文件内容）
常见问题
| 问题 | 解决方案 |
|---|
zsh 报 no matches found | URL 加双引号 |
| 查不到子分类文献 | 单独用子分类 key 查询 |
| 读错论文版本 | 先 glob **/*.tex **/*.docx 列出所有版本让用户确认 |
| 混入 PDF 附件 | 过滤 itemType 非 attachment/note |
| 需要 BibTeX | 可手动组装或用 API format=bibtex 直接导出 |
