latex-citation-enhancer · diff
v2 to v3
35 added, 456 removed. Audit A to A.
---
name: latex-citation-enhancer
description: >
- 当 Supervisor 提供 LaTeX 文档路径时，基于 Papers/ 目录和 daily papers 自动增强文档引用。
- 智能识别需要引用的位置，从论文笔记 frontmatter 生成 BibTeX 条目，自动插入 \cite{} 命令。
- 支持批量处理、质量过滤、去重，目标添加 50-80 个高质量引用。
- argument-hint: "<latex_dir_or_file> [output_bib_path] [--target-citations N]"
- allowed-tools: Read, Write, Edit, Bash, Glob
- version: 2.0
+ 当 Supervisor 需要把 Papers/ 中读过的论文转成 BibTeX 引用库时，从论文笔记
+ frontmatter 无幻觉地生成 references.bib。触发："生成 bibtex""把我读过的论文导成引用库"
+ argument-hint: "[output_bib_path]"
+ allowed-tools: Read, Write, Bash, Glob
+ version: 3.0
---
## Purpose
- 自动为 LaTeX 文档添加学术引用，基于你在 `Papers/` 目录中已阅读的论文和 `Workbench/daily/` 中的最新论文。该 skill 会：
-
- 1. **智能分析** - 扫描 LaTeX 文档，识别 200+ 个潜在引用位置
- 2. **多源检索** - 从 Papers/ (456篇) + daily papers (60+篇) 检索相关论文
- 3. **质量过滤** - 基于相关性评分、论文质量、发表年份筛选
- 4. **智能去重** - 避免重复引用，每篇论文只在最相关位置引用一次
- 5. **自动插入** - 直接在 LaTeX 文件中插入 `\cite{}` 命令
- 6. **BibTeX 生成** - 从论文笔记 frontmatter 精确提取元数据，避免幻觉
-
- **v2 新特性**：
- - ✨ 整合 daily papers，包含最新研究
- - ✨ 增强关键词提取，识别 50+ 技术术语
- - ✨ 多因子相关性评分（tags、title、venue、year、rating）
- - ✨ 自动化插入，无需手动编辑
- - ✨ 目标引用数控制（默认 50-80 个）
- - ✨ 分节平衡，避免某个章节引用过多
- - ✨ 自动备份，安全可回滚
-
- 这确保了引用的准确性、相关性和学术规范性，同时充分利用你的论文阅读历史。
-
- ## Steps (v2 Workflow)
-
- ### Phase 1: 数据准备与索引构建
-
- 1.1. **构建论文索引**
- ```bash
- python3 skills/4-writing/latex-citation-enhancer/build_paper_index.py
- ```
- - 扫描 `Papers/` 目录，提取所有论文笔记的 frontmatter
- - 生成 `paper_index.json`（456+ 篇论文）
-
- 1.2. **加载 daily papers**
- - 读取 `Workbench/daily/.candidates.json`
- - 整合最近的 arXiv 论文（60+ 篇）
- - 合并为统一的论文池（517+ 篇）
-
- 1.3. **读取现有引用**
- - 扫描 `references.bib`，提取已有 citation keys
- - 避免重复添加
-
- ### Phase 2: 智能分析与匹配
-
- 2.1. **全面扫描 LaTeX 文档**
- ```python
- # 读取所有 section 文件
- sections = read_latex_sections(base_dir)
- # introduction.tex, related_work.tex, method.tex,
- # experiments.tex, conclusion.tex, appendix.tex
- ```
-
- 2.2. **识别引用需求**（264+ 个潜在位置）
- - 按句子分割文档
- - 检测引用触发词：
- * 方法类：`methods`, `approaches`, `techniques`, `frameworks`
- * 模型类：`VLM`, `LLM`, `GUI agents`, `foundation models`
- * 评估类：`benchmarks`, `evaluation`, `metrics`
- * 技术类：`reinforcement learning`, `tool use`, `grounding`
- - 跳过已有 `\cite{}` 的句子
- - 提取上下文关键词
-
- 2.3. **多因子相关性匹配**
-
- 对每个引用位置，计算论文相关性得分：
-
- ```python
- score = 0.0
-
- # 1. Tag 匹配（强信号，权重 5.0）
- score += tag_overlap_count * 5.0
-
- # 2. Title 匹配（很强信号，权重 3.0）
- score += title_keyword_overlap * 3.0
-
- # 3. 上下文相关性（权重 1.5）
- score += context_word_match * 1.5
-
- # 4. Summary 匹配（权重 1.0）
- score += summary_keyword_match * 1.0
-
- # 5. Venue 加成
- if venue in ['CVPR', 'ICCV', 'NeurIPS', 'ICML', 'ICLR']:
- score += 3.0
- elif 'arXiv' in venue and year >= 2024:
- score += 2.0
-
- # 6. 时效性加成
- if year >= 2025: score += 2.0
- elif year >= 2024: score += 1.0
-
- # 7. Rating 加成
- if rating in ['3', '4']: score += 3.0
- elif rating == '2': score += 1.5
- ```
-
- - 为每个位置选择 top-2 最相关论文
- - 生成初步引用计划（264 个位置，528 个 citation keys）
-
- ### Phase 3: 质量过滤与优化
-
- 3.1. **质量过滤**
- - 过滤低分引用（score < 8.0）
- - 保留高质量匹配
-
- 3.2. **去重处理**
- - 每个 citation key 只保留最高分位置
- - 避免同一论文被多次引用
-
- 3.3. **分节平衡**
- - 目标：60-70 个引用位置
- - 按章节重要性分配：
- * Introduction: 高优先级（+8.0）
- * Related Work: 高优先级（+7.0）
- * Method: 中高优先级（+6.0）
- * Experiments: 中优先级（+4.0）
- * Conclusion: 中低优先级（+3.0）
- * Appendix: 低优先级（+2.0）
-
- 3.4. **最终优化**
- - 选出 top-60 引用位置
- - 对应 120 个 unique citation keys
- - 分布：
- * experiments.tex: 33 citations
- * introduction.tex: 8 citations
- * method.tex: 8 citations
- * related_work.tex: 5 citations
- * conclusion.tex: 4 citations
- * appendix.tex: 2 citations
-
- ### Phase 4: 自动插入与生成
-
- 4.1. **生成 BibTeX 条目**
-
- 从论文笔记 frontmatter 精确提取：
-
- ```python
- # Citation key 生成
- first_author = authors[0].split()[-1] # 姓氏
- cite_key = f"{first_author}{year}"
-
- # 冲突处理：添加后缀 a, b, c...
- if cite_key in existing_keys:
- cite_key += next_available_suffix()
-
- # 根据 venue 判断类型
- if 'arxiv' in venue or 'arxiv.org' in url:
- entry_type = '@article'
- journal = 'arXiv preprint arXiv:XXXX.XXXXX'
- elif venue in ['CVPR', 'ICCV', 'NeurIPS', ...]:
- entry_type = '@inproceedings'
- booktitle = f'Proceedings of {venue}'
- else:
- entry_type = '@article'
- journal = venue
- ```
-
- 4.2. **插入 \cite{} 命令**
-
- ```python
- # 在句子末尾插入（句号前）
- if sentence.endswith('.'):
- modified = sentence[:-1] + '~\\cite{key1,key2}.'
-
- # 保持原文格式
- # 不破坏 LaTeX 结构
- ```
-
- 4.3. **创建备份**
- - 所有修改的文件自动备份为 `.backup`
- - 安全可回滚
-
- 4.4. **更新 references.bib**
- - 追加新的 BibTeX 条目
- - 添加分隔注释标记
- - 保留原有条目
-
- ### Phase 5: 验证与报告
-
- 5.1. **生成报告文件**
- - `citations_final.json` - 最终引用计划
- - `citations_final.bib` - 选中的 BibTeX 条目
- - `FINAL_CITATION_REPORT.md` - 详细报告
-
- 5.2. **统计信息**
- - 总引用数
- - 分节分布
- - 论文来源统计
- - 质量分析
-
- 5.3. **输出验证清单**
- - LaTeX 编译命令
- - 需要手动检查的项目
- - 后续改进建议
-
- ## Guard
-
- ### 安全约束
-
- - **不要修改 LaTeX 文档的主要内容**，只添加 `\cite{}` 命令
- - **不要删除已有的引用**，只能追加或补充
- - **不要在同一位置重复添加相同的引用**
- - **不要修改 `Papers/` 目录中的论文笔记**
- - **不要破坏 LaTeX 结构**（表格、公式、图表等）
-
- ### 质量约束
-
- - **相关性阈值**：只添加 score ≥ 8.0 的高质量匹配
- - **引用数量控制**：目标 50-80 个引用，避免过度引用
- - **去重严格**：每篇论文只在最相关位置引用一次
- - **分节平衡**：避免某个章节引用过多（如 experiments > 40%）
-
- ### 数据约束
-
- - **不要直接编造 BibTeX 条目**——必须从 Papers/ 笔记的 frontmatter 精确提取
- - **作者信息缺失**：如果 authors 字段为空，使用 `{Unknown}` 占位，但在报告中标注
- - **年份缺失**：默认使用 2020，但在报告中标注需要手动更新
-
- ### 操作约束
-
- - **自动备份**：修改任何 LaTeX 文件前，先创建 `.backup` 文件
- - **Copilot mode**: 在实际修改 LaTeX 文件前，先输出引用计划供 Supervisor 审核
- - **可回滚**：如果 Supervisor 不满意，可以从 `.backup` 恢复
-
- ## Verify
-
- ### 自动验证（脚本完成）
-
- - [x] 论文索引成功构建，包含 400+ 篇论文
- - [x] Daily papers 成功加载（60+ 篇）
- - [x] 识别 200+ 个潜在引用位置
- - [x] 质量过滤：score ≥ 8.0
- - [x] 去重处理：无重复 citation keys
- - [x] 分节平衡：符合目标分布
- - [x] BibTeX 条目格式正确
- - [x] 所有 citation keys 有对应 BibTeX 条目
- - [x] 备份文件已创建
-
- ### 手动验证（Supervisor 完成）
-
- - [ ] **编译测试**：
- ```bash
- cd <latex_dir>
- pdflatex main.tex
- bibtex main
- pdflatex main.tex
- pdflatex main.tex
- ```
- 检查是否有编译错误
-
- - [ ] **引用位置检查**：
- - 引用是否在合适的位置？
- - 是否破坏了原文的可读性？
- - 是否有引用过密的段落？
-
- - [ ] **引用相关性检查**：
- - 随机抽查 10 个引用
- - 验证论文内容是否与上下文相关
- - 检查是否有明显不相关的引用
-
- - [ ] **BibTeX 质量检查**：
- - 检查 "Unknown" 作者的条目
- - 更新缺失的作者信息
- - 验证 arXiv ID 格式正确
-
- - [ ] **引用数量检查**：
- - 总引用数是否在 50-80 范围？
- - 是否有章节引用过多（> 40%）？
- - Introduction 和 Related Work 是否有足够引用？
+ 把 `Papers/` 中已读论文的 frontmatter（title / authors / venue / year / url）**无幻觉地**转成 BibTeX 引用库，供你在 LaTeX 写作时手动 `\cite{}`。
- - [ ] **最终确认**：
- - PDF 生成成功
- - 所有引用正确渲染
- - 参考文献列表完整
- - 如果满意，删除 `.backup` 文件
+ > **设计边界（v3 重构）**：本 skill **只做 BibTeX 生成**，不再自动决定"在哪句话插哪篇引用"。
+ > 原 v2 的 keyword-score auto-insert 已移除——关键词重叠 ≠ 该论文支撑这句 claim，自动插引用会引入
+ > 不相关甚至错误的引用，违背 evidence-driven 原则。引用位置由作者判断，工具只保证**条目准确**。
- ## Examples
+ ## Steps
- ### Example 1: 完整工作流（实际案例）
+ ### Step 1：构建论文索引
```bash
- # Supervisor 提供 LaTeX 项目目录
- /latex-citation-enhancer /Users/kendrickstein/Code/Reward-Agent/writing
- ```
-
- **执行过程**：
- ```
- [1/6] Loading paper sources...
- ✓ Loaded 456 papers from Papers/
- ✓ Loaded 61 papers from daily summaries
- ✓ Total paper pool: 517 papers
-
- [2/6] Analyzing LaTeX content...
- ✓ Read 7 section files
- ✓ Found 264 potential citation locations
-
- [3/6] Matching papers to citation needs...
- ✓ Generated 264 citation recommendations
- ✓ Found 528 candidate citations
-
- [4/6] Quality filtering & optimization...
- ✓ Filtered to 71 high-quality locations
- ✓ Optimized to top 60 citations
- ✓ Final unique citation keys: 120
-
- [5/6] Inserting citations...
- ✓ Modified introduction.tex: 8 citations
- ✓ Modified related_work.tex: 5 citations
- ✓ Modified method.tex: 8 citations
- ✓ Modified experiments.tex: 33 citations
- ✓ Modified conclusion.tex: 4 citations
- ✓ Modified appendix.tex: 2 citations
-
- [6/6] Generating reports...
- ✓ Appended 120 entries to references.bib
- ✓ Created backups with .backup extension
- ✓ Generated FINAL_CITATION_REPORT.md
+ python3 skills/4-writing/latex-citation-enhancer/build_paper_index.py
```
- **结果**：
- - 添加了 120 个高质量引用
- - 分布在 60 个位置
- - 所有文件已备份
- - 编译成功，无错误
-
- ### Example 2: 指定输出路径
-
- ```bash
- /latex-citation-enhancer ~/thesis/chapter3/ ~/thesis/references.bib
- ```
+ 扫描 `Papers/` 所有笔记的 frontmatter，输出 `paper_index.json`（含 title / authors / venue / year / url / tags / rating）。
- ### Example 3: 控制引用数量
+ ### Step 2：生成 BibTeX
```bash
- # 如果需要更少的引用（如 40 个）
- # 修改 auto_insert_citations.py 中的 target 参数
- /latex-citation-enhancer ~/paper/ --target-citations 40
+ python3 skills/4-writing/latex-citation-enhancer/generate_bibtex.py
```
- ### Example 4: 典型引用插入效果
-
- **原文**（introduction.tex）：
- ```latex
- GUI task evaluation aims to determine whether a GUI agent has
- successfully completed a user instruction. Benchmarks typically
- implement evaluation through task-specific verification scripts.
- ```
+ 从 `paper_index.json` 生成 `references.bib`：
+ - citation key = `{FirstAuthorLastName}{Year}`，冲突自动加后缀 `a/b/c`
+ - venue 含 arxiv → `@article` + `journal={arXiv preprint arXiv:XXXX.XXXXX}`；会议 → `@inproceedings`
+ - 所有字段直接取自 frontmatter，**不调用外部 API、不编造**
- **增强后**：
- ```latex
- GUI task evaluation aims to determine whether a GUI agent has
- successfully completed a user instruction~\cite{Unknown2025ġ,Tomic2025}.
- Benchmarks typically implement evaluation through task-specific
- verification scripts.
- ```
+ 如需只导出某主题/某几篇，先按 tag 或 title 过滤 `paper_index.json` 再生成（或手动从输出里挑 key）。
- **原文**（related_work.tex）：
- ```latex
- VLM-as-reward methods replace manual verifiers with vision-language
- models that judge completion from screenshots.
- ```
+ ### Step 3：作者手动引用
- **增强后**：
- ```latex
- VLM-as-reward methods replace manual verifiers with vision-language
- models that judge completion from screenshots~\cite{Chen2024e,Xu2026a}.
- ```
+ 在 LaTeX 中由作者在**需要证据支撑的具体 claim** 处插入 `\cite{key}`。工具不代替这一判断。
- ### Example 5: 生成的 BibTeX 条目
+ ## Guard
- ```bibtex
- @inproceedings{Qin2025,
- title={UI-TARS: Pioneering Automated GUI Interaction with Native Agents},
- author={Yujia Qin and Yining Ye and Junjie Fang and ...},
- booktitle={Proceedings of ICLR 2025},
- year={2025}
- }
+ - **不编造 BibTeX**：所有条目必须来自 `Papers/` 笔记 frontmatter；作者/年份缺失则填 `{Unknown}` / 标注，不猜。
+ - **不自动插入 `\cite{}`**：不扫描 LaTeX 正文、不按关键词决定引用位置。
+ - **不修改 Papers/ 笔记**。
+ - 覆盖已有 `references.bib` 前先确认（或写到新路径）。
- @article{Lu2024,
- title={OmniParser for Pure Vision Based GUI Agent},
- author={Yadong Lu and ...},
- journal={arXiv preprint arXiv:2408.00203},
- year={2024},
- url={https://arxiv.org/abs/2408.00203}
- }
+ ## Verify
- @inproceedings{Hong2023,
- title={CogAgent: A Visual Language Model for GUI Agents},
- author={Wenyi Hong and Weihan Wang and ...},
- booktitle={Proceedings of CVPR 2024},
- year={2023}
- }
- ```
+ - [ ] `paper_index.json` 生成，条目数 ≈ Papers/ 论文数
+ - [ ] `references.bib` 中每个 entry 字段来自 frontmatter，无占位幻觉数字
+ - [ ] citation key 无重复（冲突已加后缀）
+ - [ ] 标注了 author/year 缺失的条目供手动补全
## Notes
- ### 使用建议
-
- - **首次使用**：建议先在测试文档上运行，熟悉工作流程
- - **大型项目**：对于 > 50 页的论文，预计需要 2-3 分钟处理时间
- - **多次运行**：可以多次运行逐步完善引用，已有引用不会被重复添加
- - **手动调整**：自动插入后，建议手动检查 10-20% 的引用位置
-
- ### 技术细节
-
- - **论文索引缓存**：`paper_index.json` 每次运行时重新构建，确保使用最新论文库
- - **引用风格**：默认使用 `~\cite{}`（波浪号防止换行），如需其他风格可全局替换
- - **BibTeX 生成**：直接从 Papers/ 笔记的 frontmatter 提取，无需外部 API
- - **作者格式**：自动转换为 BibTeX 标准格式（`LastName, FirstName and ...`）
- - **Citation key 冲突**：自动添加后缀 a, b, c 避免重复
-
- ### 常见问题
-
- **Q: 为什么有些 citation key 是 "Unknown2025"？**
- A: 论文笔记中缺少作者信息。建议手动更新 `references.bib` 中的作者字段。
-
- **Q: 引用数量太多/太少怎么办？**
- A: 修改 `auto_insert_citations.py` 中的 `target` 参数（默认 60）。
-
- **Q: 如何回滚修改？**
- A: 所有修改的文件都有 `.backup` 备份，直接恢复即可：
- ```bash
- cd secs/
- mv introduction.tex.backup introduction.tex
- ```
-
- **Q: 某个引用不相关，如何删除？**
- A: 手动编辑 LaTeX 文件，删除对应的 `\cite{}` 命令。
-
- **Q: 如何添加特定论文的引用？**
- A: 确保论文笔记在 `Papers/` 目录中，重新运行 skill。或手动添加到 `references.bib`。
-
- ### 性能指标
-
- - **处理速度**：~264 个位置 / 2 分钟
- - **准确率**：相关性匹配 > 85%（基于人工抽查）
- - **覆盖率**：识别 > 90% 的需要引用的位置
- - **时间节省**：相比手动添加，节省 4-6 小时
-
- ### 文件输出
-
- 执行后会生成以下文件：
-
- **主要输出**：
- - `references.bib` - 更新的参考文献（追加新条目）
- - `secs/*.tex` - 修改的 LaTeX 文件（已插入引用）
- - `secs/*.tex.backup` - 原始文件备份
-
- **报告文件**：
- - `FINAL_CITATION_REPORT.md` - 详细执行报告
- - `citations_final.json` - 最终引用计划（JSON）
- - `citations_final.bib` - 选中的 BibTeX 条目
-
- **中间文件**（可选查看）：
- - `citation_plan_v2.json` - 完整引用计划（264 个位置）
- - `citation_plan_filtered.json` - 过滤后计划（71 个位置）
- - `citation_report_v2.md` - 详细分析报告
- - `new_citations.bib` - 所有候选 BibTeX 条目（528 个）
-
- ### 后续改进方向
-
- - [ ] 支持自定义引用风格（IEEE, ACM, APA 等）
- - [ ] 交互式审核模式（逐个确认引用）
- - [ ] 更智能的作者名提取
- - [ ] 支持从 arXiv API 自动补全元数据
- - [ ] 引用密度热力图可视化
- - [ ] 与 Zotero 集成（如果可用）
-
- ### 相关 Skills
-
- - **paper-digest** - 消化新论文，添加到 Papers/ 目录
- - **daily-papers** - 获取最新 arXiv 论文
- - **paper-writing** - 学术论文写作指导
- - **paper-review** - 论文自审工具
+ - `paper_index.json` 每次运行重建，始终反映最新 Papers/。
+ - 想要更高引用质量：先用 `paper-digest` 补全相关论文的 frontmatter（authors/venue/year），再重跑本 skill。
+ - 相关 skills：`paper-digest`（补论文）、`daily-papers`（拉新论文）。