/citation-assistant

name: citation-assistant
description: Use when the user needs academic citations, BibTeX, venue/author quality checks, or help filling [CITE] placeholders. Triggers include 文献引用、找引用、citation、bib、参考文献、替换不规范引用、查询作者 H-index、判断期刊/会议质量。

Citation Assistant 学术文献引用助手

⚠️ 核心原则

1. **必须通过 `scripts/` 目录中的脚本执行**，禁止手动编写 curl 命令 2. **禁止使用 Tavily、WebSearch 等非学术搜索工具**进行文献检索 3. **语义优先**：理解引用意图，避免仅用关键词检索 4. **不自动修改文稿**：所有推荐需用户确认后再应用

---

运行路径（Codex / Claude Code / Cursor）

以本次加载的 `SKILL.md` 所在目录为 Skill 根目录，**不要使用论文项目的当前工作目录来定位脚本**，也不要假设客户端会注入 `CLAUDE_SKILL_ROOT` 等环境变量。

下面示例中的 `CITATION_ASSISTANT_ROOT` 是自行设置的 shell 变量：将其设为本次加载的 Skill 的绝对路径（包含 `SKILL.md`、`scripts/` 和 `data/`）。每次新的 shell 调用都需重新设置它，或直接使用脚本的完整绝对路径；路径始终加双引号。

# 将此路径替换为本次加载的 SKILL.md 所在目录
CITATION_ASSISTANT_ROOT="/absolute/path/to/citation-assistant"
bash "${CITATION_ASSISTANT_ROOT}/scripts/venue_info.sh" "Nature Medicine"

脚本从自身位置读取同一安装目录内的 `.env` 和 `data/`，可以在任意论文目录运行。在 Codex 中可通过 `$citation-assistant` 显式调用，也可用自然语言请求引用检索、BibTeX 或期刊质量查询。

📦 可用脚本

依赖：Bash、`curl`、`jq`、支持 `-json` 的 `sqlite3`。搜索、作者查询和 DOI 转换需要网络；CCF / IF 查询只读本地数据库。

下表中的相对路径以 Skill 根目录为基准；从论文目录调用时使用上述绝对路径。

| 脚本 | 用途 | 用法 | |------|------|------| | `search_papers.sh` | 默认文献检索：S2 搜索持续 429 后自动转 CrossRef，结果带来源 | `bash scripts/search_papers.sh "query" [limit]` | | `s2_search.sh` | 少量高相关结果检索（含 arXiv 判断） | `bash scripts/s2_search.sh "query" [limit]` | | `s2_bulk_search.sh` | 批量拉取候选结果并按本地 limit 输出（含 arXiv 判断） | `bash scripts/s2_bulk_search.sh "query" "year_range" limit` | | `author_info.sh` | 作者信息查询（H-index） | `bash scripts/author_info.sh "author_id"` | | `venue_info.sh` | 期刊综合查询 | `bash scripts/venue_info.sh "venue_name"` | | `ccf_lookup.sh` | CCF 分级查询 | `bash scripts/ccf_lookup.sh "venue_name"` | | `if_lookup.sh` | 影响因子查询 | `bash scripts/if_lookup.sh "journal_name"` | | `doi2bibtex.sh` | DOI 转 BibTeX | `bash scripts/doi2bibtex.sh "doi"` | | `crossref_search.sh` | CrossRef 搜索（fallback） | `bash scripts/crossref_search.sh "query" [limit]` |

---

🆕 增强功能

arXiv 文章智能判断

搜索结果会自动标记 arXiv 文章的引用状态：

| 状态 | 条件 | 推荐建议 | |------|------|----------| | `recommended` | arXiv + 引用 ≥ 100 | ✅ 高影响力 arXiv，可引用 | | `caution` | arXiv + 引用 < 100 | ⚠️ 低引用 arXiv，谨慎引用 | | `normal` | 正式发表 | ✅ 正式发表 |

**配置引用阈值**（默认 100）：

export ARXIV_CITATION_THRESHOLD=100

作者信息查询

搜索结果包含前 3 位作者的 ID，可用于查询 H-index：

# 查询作者 H-index、总引用量、论文数
bash "${CITATION_ASSISTANT_ROOT}/scripts/author_info.sh" "18119920"

返回示例：

{
  "name": "Daquan Zhou",
  "hIndex": 25,
  "citations": 8500,
  "papers": 42
}

---

🔄 工作流程

Step 1: 解析需求

识别用户需求类型：

• **[CITE] 占位符**：提取上下文，构造语义查询
• **替换不规范引用**：分析原文引用的语义意图
• **期刊查询**：直接查询 CCF/IF 数据库
• **作者质量评估**：查询第一/通讯作者的 H-index

Step 2: 语义化查询构造

| 引用目的 | 查询策略示例 | |----------|--------------| | 事实背书 | "chest radiography most widely used imaging test globally statistics" | | 方法引用 | "attention mechanism transformer neural machine translation" | | 背景介绍 | "deep learning medical image analysis survey review" |

Step 3: 执行搜索

• 日常文献检索优先使用 `search_papers.sh`：S2 相关性搜索，持续 429 时自动转 CrossRef；若用户明确只接受 S2 数据，则使用 `s2_search.sh`
• 需要减少请求次数、批量拉取候选结果并再做筛选时，使用 `s2_bulk_search.sh`

# 默认检索入口（自动处理 S2 持续限流）
bash "${CITATION_ASSISTANT_ROOT}/scripts/search_papers.sh" "YOUR_QUERY" 10

# 批量候选结果（bulk endpoint），再由脚本按 limit 输出前 N 条
bash "${CITATION_ASSISTANT_ROOT}/scripts/s2_bulk_search.sh" "YOUR_QUERY" "2020-" 20

**直接使用原始 S2 脚本且返回 429 错误时**，可显式使用 CrossRef fallback（`search_papers.sh` 已自动处理）：

bash "${CITATION_ASSISTANT_ROOT}/scripts/crossref_search.sh" "YOUR_QUERY" 20

自动降级限定期刊论文、会议论文与预印本类记录；检查 CrossRef 的 `work_type`，预印本不能当作已正式发表。

检查 `source` / `search_method`：CrossRef 结果属于独立来源的文献匹配，不应描述为 S2 的相关性排名。其作者 ID、arXiv 判断等不可用字段为 `null` / `unknown`，不要调用 `author_info.sh` 查询空 ID，也不要补造 H-index。引用量必须标注数据来源，不直接混用不同来源的计数。降级后的结果同样需要核实是否支持原文观点。

Step 4: 评估文献质量

# 查询期刊质量
bash "${CITATION_ASSISTANT_ROOT}/scripts/venue_info.sh" "Nature Medicine"

# 查询作者 H-index
bash "${CITATION_ASSISTANT_ROOT}/scripts/author_info.sh" "AUTHOR_ID"

Step 5: 生成 BibTeX

bash "${CITATION_ASSISTANT_ROOT}/scripts/doi2bibtex.sh" "10.1038/s41591-020-0792-9"

Step 6: 生成中文推荐报告

输出格式示例：

## 引用推荐报告

### [CITE] 位置 1

**原文上下文**：
> In chest radiography---arguably the most widely used imaging test globally [CITE]---

**推荐文献**：

#### 推荐 1: Wu2020 - CheXpert: A large chest radiograph dataset...

**质量指标**：
| 维度 | 值 | 说明 |
|------|-----|------|
| CCF 分级 | N/A | 非CS领域期刊 |
| JCR 分区 | Q1 | 顶级医学影像期刊 |
| 影响因子 | 29.1 | 极高影响力 |
| 引用量 | 3500+ | 高被引文献 |
| arXiv 状态 | normal | 正式发表 |

**推荐理由**：顶级期刊发表，直接支持原文论点。

**BibTeX**：
```bibtex
@article{Wu2020, ... }

**建议用法**：将 `[CITE]` 替换为 `~\cite{Wu2020}`

---

## ⚙️ 配置

### Semantic Scholar API Key（强烈推荐）

```bash
# 在 Skill 目录创建 .env 文件
echo 'S2_API_KEY="your_key_here"' > "${CITATION_ASSISTANT_ROOT}/.env"

# 获取 API Key: https://www.semanticscholar.org/product/api/api-key

| 模式 | 速率限制 | 推荐场景 | |------|----------|----------| | 有 API Key | 1 次/秒 | 日常使用（推荐） | | 无 API Key | 共享限额 | 极易触发 429 |

arXiv 引用阈值（可选）

# 默认 100，可在 .env 中配置
echo 'ARXIV_CITATION_THRESHOLD=100' >> "${CITATION_ASSISTANT_ROOT}/.env"

---

🚨 错误处理

429 Rate Limit

1. S2 脚本已自动进行有界重试（默认最多 2 次），优先遵守 `Retry-After`；不要连续重复调用或把 429 当作无效密钥 2. 仍失败时等待更长时间，并说明当前接口受限；带 Key 或切换 bulk 接口也不保证解除限流 3. 论文检索可使用 `crossref_search.sh` fallback；作者 H-index 无此替代，无法获取时明确标记未知

401 / 403

脚本不重试认证或权限错误。检查 Skill 目录的 `.env` / `S2_API_KEY` 及接口权限，不输出密钥。

无搜索结果

1. 简化关键词 2. 使用英文查询 3. 尝试 CrossRef fallback

---

📊 质量评估维度

| 维度 | 权重 | 计算 | |------|------|------| | CCF 分级 | 基础分 | A=100, B=70, C=40 | | JCR 分区 | 基础分 | Q1=80, Q2=60, Q3=40, Q4=20 | | 中科院分区 | 基础分 | 1区=90, 2区=70, 3区=50, 4区=30 | | 影响因子 | 30% | IF × 5 (上限50) | | 引用量 | 20% | log₁₀(citations+1) × 10 (上限50) | | 年份 | 10% | (year-2015) × 2 (上限30) | | 作者 H-index | 10% | 第一作者 H-index × 2 (上限30) |

**arXiv 处理**：

• 引用 ≥ 100：正常评分
• 引用 < 100：降低优先级 (-20 分)
• 有正式发表版本优先