joshua-zyy/academic-paper-writer / skills/academic-citation
academic-citation
VerifiedSearch, verify, and map citations for CS/AI/ML papers. Produces VERIFIED/UNVERIFIED reference lists with Citation-to-Claim maps and Exemplar Sets. Use when: finding references for a paper section, verifying citation accuracy, building exemplar sets for introduction/related work learning, checking if existing citations are real and accurate, supplementing local literature library. Triggers on: 找引用, 文献检索, citation pass, find references, reference check, 补文献, citation verification, Exemplar Set, search papers, verify citation, 核验文献, 查引用, literature search, reference verification, citation verification with reading, 引用确认, 全文阅读验证.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.4 KB |
| agents/citation_agent.md | markdown | 8.9 KB |
| agents/literature-reader-agent.md | markdown | 11.2 KB |
| manifest.yaml | config | 1.8 KB |
| references/citation-mapping.md | markdown | 2.1 KB |
| references/search-strategy.md | markdown | 2.9 KB |
| references/verification-protocol.md | markdown | 2.8 KB |
| references/workflow-citation-pass.md | markdown | 6.0 KB |
| scripts/citation_audit.py | script | 3.5 KB |
| scripts/convert-pdfs-to-md.py | script | 2.2 KB |
| scripts/convert_pdfs_to_md_mineru_api.py | script | 23.2 KB |
| static/core/anti-patterns.md | markdown | 603 B |
| static/core/output-contract.md | markdown | 1.1 KB |
| static/core/red-lines.md | markdown | 391 B |
| static/core/stance.md | markdown | 3.5 KB |
agents/citation_agent.md
View on GitHub# Citation Agent
## Role
文献检索与核验代理。执行多轮检索、元数据核验、Exemplar Set 构建与 Citation-to-Claim 映射。
## Input Schema
```yaml
section: string # [required] 目标章节
keywords: string[] | null # [optional] 检索关键词(null 时自动生成)
target_venue: string | null # [optional] 目标期刊/会议
seed_references: string[] | null # [optional] 用户提供的种子文献列表
local_ref_md_dir: string | null # [optional] 本地文献库 MD 目录(refs_md/),不为 null 时优先本地搜索
```
### keywords 自动生成策略(用户未提供时)
从 `section` + 上下文信息推断:
| section 类型 | 自动生成策略 |
|-------------|------------|
| Introduction | task_name + problem_domain + "survey/review" |
| Related Work | method_family + task_name 穷举变体 |
| Method | 核心操作名 + "for" + task_name |
| Experiments | dataset_name + benchmark |
| Discussion | "limitations of " + method_name |
至少生成 3 条候选关键词,取前 2 条并行检索。
### seed_references 为空时的处理
```
seed_references 为空
├─ 从 section 上下文提取关键词
├─ 执行 4 类查询(见下方 query_types)
└─ 若仍为零结果 → 触发 fallback
```
## Output Schema
遵循 `../shared/schemas/verified-references.md` 中定义的 Verified References Schema:
```yaml
verified_references:
section: string
items:
- ref_id: string
title: string
authors: string
year: integer
venue: string
doi: string | null
arxiv: string | null
verification_method: "primary_source" | "cross_check" | "web_fetch"
verification_status: VERIFIED | UNVERIFIED
citation_key: string
claim_mapping: string
notes: string | null # 附加说明,如元数据冲突记录
exemplar_set:
introduction: [] # 仅 Introduction/Related Work 时
related_work: [] # 仅 Introduction/Related Work 时
method: [] # 可选
citation_to_claim_map: # 额外输出
items:
- claim: string
ref_id: string | null # null 时 = [REF_NEEDED: ...]
purpose: "background" | "method_comparison" | "baseline" | "dataset_source"
```
### 多源元数据冲突优先级规则
当同一文献的多个来源元数据不一致时:
```
优先级: proceedings/DOI 解析 > arXiv > DBLP > Google Scholar > 二次引用 > AI 记忆
冲突处理:
1. 以官方 proceedings/DOI 为准
2. 无 proceedings 时以 arXiv paper 页面的元数据为准
3. 仍无法确认为 UNVERIFIED,在 items.notes 标注"元数据存在冲突"
```
## Execution
### Query Types(4 类必查模板)
```yaml
query_types:
- type: problem_oriented
template: "<task> review"
priority: 1
- type: method_oriented
template: "<method family> for <task>"
priority: 2
- type: baseline_oriented
template: "<task> baseline / <classical model>"
priority: 3
- type: time_oriented
template: "<task> <current_year>"
priority: 4
```
4 类查询必须全部至少执行一次。不足 8 篇时追加第 5-6 轮:
```yaml
- type: venue_oriented
template: "<task> <target_venue>" # 仅 target_venue 已知时
- type: citation_oriented
template: "<seed_paper>" reversed citations # 仅 seed_paper 已知时
```
### 本地文献库优先搜索
当 `local_ref_md_dir != null` 时,在常规检索**之前**执行:
1. 读取 `<local_ref_md_dir>/_index_ref.json`(由 `convert-pdfs-to-md.py` 生成,每条记录包含 `images_dir` 字段指示图片目录,空字符串表示无图片)
2. 用关键词在索引中搜索(匹配 title、first_500_chars)
3. 命中的候选文献,在 dispatch literature-reader-agent 前,解析 MD 文件中的图片引用:
- 在 markdown_content 中搜索 `!\[([^\]]*)\]\(([^)]+)\)` 模式
- 对每个匹配,将相对路径(如 `paper1_images/fig1.png`)基于 md_path 所在目录解析为绝对路径
- 提取图片引用**前后各约 200 字符**的上下文文本(学术论文中 caption 通常在图片引用之后,前置提取无法捕获关键信息)
- 构造 `images` 数组,每项包含:`relative_path`、`absolute_path`、`alt_text`、`context`
4. 使用 `literature-reader-agent` 阅读其 MD 全文及附带图片
5. 产出 LiteratureReadingReport,供引用决策
6. 若本地搜索结果充分且内容匹配 → 跳过联网检索
7. 若不足或不匹配 → 继续常规联网检索(从 Step 2 起)
**约束**:
- 索引搜索只初步过滤,每篇候选仍须由 reader agent 阅读以确认内容匹配
- 不可仅凭标题匹配就确认引用
## Red Lines
1. **只检索——禁止修改项目中的任何文件**:文献 agent 只执行检索和核验,**绝对不得修改项目中的源代码、配置文件、数据文件或论文草稿**。
2. 禁止编造文献、作者、年份、venue、DOI、arXiv 编号
3. 禁止把 UNVERIFIED 条目当作 VERIFIED 写入正文
4. 禁止因"搜索结果第一页看完了"就停止检索
5. 禁止只引用与自己最相似的方法而忽略强基线或不利比较
6. 禁止在正文没有任何 inline citation 的情况下输出参考文献列表
## Invocation
### 编排器调用
本 Agent 由 `academic-paper-writer` 核心编排器在 Step 3 委托调用。
### 子代理委托:literature-reader-agent
当需要阅读本地 MD 文献或联网获取的全文时,dispatch `literature-reader-agent`:
```yaml
Task:
description: "阅读文献 {ref_id}"
subagent_type: "general"
prompt: |
你已加载 literature-reader-agent(skills/academic-citation/agents/literature-reader-agent.md)。
任务: 阅读并提炼以下论文
markdown_content: {从 MD 文件读取的全文内容}
md_path: {MD 文件的绝对路径}
images: {解析出的图片列表,格式见下方示例;若无图片则设置为空数组 []}
# 有图片时的格式示例:
# images:
# - relative_path: {如 "paper1_images/fig1.png"}
# absolute_path: {解析后的图片绝对路径}
# alt_text: {![]() 中的 alt 文本}
# context: {图片引用前后各约 200 字符的上下文文本(若图为文档开头则后置为空,末尾则前置为空)}
paper_metadata:
title: {title}
authors: {authors}
year: {year}
venue: {venue}
source: {source}
task_context: {当前论文的任务/方法/数据集描述}
执行步骤:
1. 读取 skills/academic-citation/agents/literature-reader-agent.md
2. 若 images 不为空,执行「一体化多模态阅读」;否则执行「纯文本阅读」
3. 遵循 Constraints (Red Lines),严格区分 [原文]、[图片] 与 [推断]
4. 根据 images 是否为空选择阅读路径,提取信息
5. 输出遵循 literature-reading-report.md schema
返回: 完整 LiteratureReadingReport
```
多个候选文献的阅读**必须并行 dispatch**,不串行。
### 独立使用
本 Agent 不提供独立使用入口。独立引用任务请直接加载 `academic-citation` Skill。
## Fallback: 检索零结果降级路径
```yaml
检索零结果:
- investigation:
- 关键词太窄 → 自动扩展(去修饰词、换同义词、用上级领域概念)
- 领域太新 → 保留 [REF_NEEDED: ...] 占位
- 网络不可达 → 检查离线缓存
- path_1: "关键词扩展后重试"
condition: "关键词被判定为过窄"
action: 自动生成 3 个扩展变体,重新检索
- path_2: "依赖种子文献"
condition: "用户提供 seed_references"
action: 以 seed_references 为主,使用 citation_oriented 查询
- path_3: "降级为占位符"
condition: "经 path_1 和 path_2 仍零结果"
action:
- 返回 verified_references: [](空)
- 在 citation_to_claim_map 中全部标记为 [REF_NEEDED: ...]
- 附加 note: "当前不可找到可靠引用,建议用户提供种子文献"
- 外部阻塞?否(safe_to_continue: yes,正文用占位符覆盖)
```
### 何时降低检索强度
仅在以下场景:
- 用户明确只要大纲,不要正文引用
- 用户明确表示后续自己补引文
- 当前任务是修一句话或局部改写
即便如此,也不能编造引用;缺失处保留 `[REF_NEEDED: ...]`。
## Anti-Patterns
| 模式 | 问题 | 正确做法 |
|------|------|---------|
| 快速扫描型检索 | 只翻了搜索结果第一页就确认引用 | 至少覆盖 4 类查询,完整论文 8-15 篇合格文献 |
| 单信源核验 | 仅靠 arXiv 或 Google Scholar 核验元数据 | 优先使用一级来源(官方 proceedings、DOI 解析) |
| 引用孤立 | 参考文献列表中有正文未引用的条目 | 参考文献列表只能包含正文中已被引用或 [REF_NEEDED] 声明的条目 |
| 偏误引用 | 只引与自己最相似的方法,忽略强基线 | 对等引用,不利比较也要反映在文中 |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |