journal-if

期刊影响因子查询

通过双来源级联查询期刊影响因子：捆绑的 CSV 缓存（约 200 种常见期刊）→ OpenAlex API（可查询任意期刊的近似 2 年影响因子）。

重要规则： 查询时始终使用 journal_if.py。切勿猜测影响因子——影响因子每年都会变化，也因版本而异。

快速参考

用户想要……	层级	命令
查询期刊影响因子	读取	python3 journal_if.py lookup "Nature Medicine"
搜索期刊	读取	python3 journal_if.py search "cancer immunology"
处理期刊列表	读取	python3 journal_if.py batch journals.txt
仅使用缓存（不联网）	读取	python3 journal_if.py --offline lookup "Cell"
检查缓存状态	读取	python3 journal_if.py cache status
刷新上游 CSV	写入	python3 journal_if.py cache update
机器可读的 CLI 合约	读取	python3 journal_if.py schema
单个子命令的架构	读取	python3 journal_if.py schema lookup

输出格式

当 CLI 未连接到终端（输出通过管道传输或由 Agent 捕获）时，标准输出为稳定的 JSON 封装；在 TTY 中运行时，则显示为人类可读的视图。 如需指定格式：--format json|table|human|auto。--json 是兼容旧版本的别名，等同于 --format json。

封装结构：

• 成功：{ "ok": true, "data": {...}, "meta": { "schema_version", "cli_version", "latency_ms" } }
• 部分成功（批处理）：{ "ok": "partial", "data": { "succeeded": [...], "failed": [...] }, "meta": {...} }
• 错误：{ "ok": false, "error": { "code", "message", "retryable", ... }, "meta": {...} }

退出代码

代码	含义
0	成功（包括部分成功）
1	运行时错误 / 上游错误
2	验证错误 / 输入无效（缺少文件、标志无效）
3	未找到（未匹配到期刊）

错误代码（位于 error.code 中）

代码	可重试	退出代码	含义
not_found	否	3	查询已完成，但没有来源匹配
upstream_unavailable	是	1	OpenAlex API 暂时不可用；请稍后重试或使用 --offline
file_not_found	否	2	输入文件路径不存在
validation_error	否	2	参数错误或标志组合无效
runtime_error	是	1	意外的内部错误

数据来源

1. 捆绑的 CSV — 涵盖生命科学、医学、化学、物理学和工程学领域的约 200 种顶级期刊。根据 JCR 数据整理，并随技能一同提供。始终可用，查询即时完成。

2. OpenAlex API — 免费的开放 API，根据引文数量计算近似的 2 年影响因子。涵盖几乎所有学术期刊。该数值不同于官方 JCR 影响因子——它是按照相同公式计算的引文率指标（第 Y 年对第 Y-1 年和第 Y-2 年发表的内容的引文数，除以这两年的可引用内容数），但使用的是 OpenAlex 自己的文章分类。适用于排名和比较；在正式场合不得将其称为“JCR 影响因子”。

何时使用哪种来源

场景	来源
快速查询主要期刊	捆绑的 CSV（即时）
小众或较新的期刊	自动回退到 OpenAlex
正式投稿 / 申请资助	注意：OpenAlex IF ≠ 官方 JCR IF。仅可注明为近似值。
批量处理多个期刊	缓存命中的使用 CSV，未命中的使用 OpenAlex
离线 / 隔离网络	使用 --offline 标志（仅限捆绑的 CSV）

工作流

第 1 步：识别意图

意图	操作
“Nature 的影响因子是多少？”	lookup "Nature"
“比较 Cell 和 Science 的影响因子”	运行两次 lookup，比较结果
“哪些免疫学期刊的影响因子 > 20？”	执行 search "immunology"，然后筛选
“处理这份期刊列表”	batch journals.txt
“这是一本高影响力期刊吗？”	执行 lookup，然后结合学科背景解读影响因子

步骤 2：执行

运行相应的 journal_if.py 命令。脚本会处理：

1. 本地 CSV 查询（即时，约 200 种精选期刊）
2. OpenAlex API 回退（自动，近似 2 年 IF）
3. 模糊匹配——识别细微的名称变体

步骤 3：展示结果

• 显示期刊名称、影响因子和数据年份
• 注明数据来源（CSV 缓存或 OpenAlex 近似值）
• 对于搜索结果：显示包含 IF、年份和类别的表格

了解影响因子

IF 范围	常见等级	示例
> 30	顶尖（前 0.1%）	Nature（64.8）、Science（56.9）、Cell（64.5）
20–30	卓越（前 1%）	Cancer Cell（50.3）、Immunity（32.4）
10–20	优秀（前 5%）	Nature Communications（16.6）、Sci Adv（13.6）
5–10	较强（前 15%）	eLife（7.7）、Cell Reports（8.8）
2–5	良好	PLOS ONE（3.7）、Sci Rep（4.6）
< 2	小众 / 新刊	许多领域专业期刊和新期刊

注意事项：

• IF 因领域而异，差异可能很大——顶尖数学期刊的 IF 可能 < 5，而中等水平的肿瘤学期刊 IF 可能 > 10。
• 务必在同一领域内比较 IF。
• IF 数据年份很重要；数值每年都会变化。
• OpenAlex 近似 IF 与官方 JCR IF 不同；应将其视为排名指标，而非认证数值。

批量处理

创建一个文本文件，每行填写一个期刊名称：

Nature Medicine
Journal of Biological Chemistry
Proceedings of the National Academy of Sciences

然后运行：

python3 journal_if.py batch journals.txt

故障排除

问题	解决方案
“未找到数据”	尝试较短或不同的名称；使用 search 进行模糊匹配
OpenAlex 返回的 IF 为 0 或 None	期刊可能太新（需要 2 年以上的数据）；使用 --offline 仅检查缓存
OpenAlex IF 与 JCR 不同	这是预期情况——OpenAlex 使用自己的文章分类。可用于排名，不适用于正式引用。
缓存下载失败	检查网络；捆绑的 CSV 仍可离线使用
匹配到错误的期刊	使用更具体的名称；模糊匹配器会选择最接近的子串匹配项