Skip to content

joshua-zyy/academic-paper-writer / skills/academic-citation

academic-citation

Verified

Search, 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, 引用确认, 全文阅读验证.

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] 声明的条目 |
| 偏误引用 | 只引与自己最相似的方法,忽略强基线 | 对等引用,不利比较也要反映在文中 |
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: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
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: 115kUpdated Claude CodeCodexVerifiedInstall
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: 115kUpdated Claude CodeCodexVerifiedInstall