journal-if

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Journal Impact Factor Lookup

—

Look up journal impact factors using a two-source cascade: bundled CSV cache (~200 common journals) → OpenAlex API (approximate 2-year IF for any journal).

Critical rule: Always use

journal_if.py

for lookups. Never guess impact factors — they change yearly and vary by edition.

上方为Claude Code字段，下方为OpenClaw/SkillsMP字段 --- author: Agents365-ai category: Academic Research version: 1.0.0 created: 2026-07-14 updated: 2026-07-14 github: https://github.com/Agents365-ai/journal-if homepage: https://github.com/Agents365-ai/journal-if metadata: version: 1.0.0 openclaw: requires: bins: - python3 emoji: "📊" homepage: https://github.com/Agents365-ai/journal-if os: ["macos", "linux", "windows"]

Quick Reference

期刊影响因子查询

User wants...	Tier	Command
Look up IF of a journal	read	`python3 journal_if.py lookup "Nature Medicine"`
Search for a journal	read	`python3 journal_if.py search "cancer immunology"`
Process a list of journals	read	`python3 journal_if.py batch journals.txt`
Cache-only (no network)	read	`python3 journal_if.py --offline lookup "Cell"`
Inspect cache state	read	`python3 journal_if.py cache status`
Refresh upstream CSV	write	`python3 journal_if.py cache update`
Machine-readable CLI contract	read	`python3 journal_if.py schema`
Schema for one subcommand	read	`python3 journal_if.py schema lookup`

采用双数据源级联方式查询期刊影响因子：内置CSV缓存（约200种常见期刊）→ OpenAlex API（为任意期刊提供近似的2年期IF）。

核心规则： 所有查询必须使用

journal_if.py

，严禁猜测影响因子——影响因子每年更新，且不同版本数值存在差异。

Output format

快速参考

Stdout is a stable JSON envelope when the CLI is not attached to a terminal (piped or captured by an agent), and a human-readable view when run on a TTY. To force a format:

--format json|table|human|auto

--json

is a back-compat alias for

--format json

Envelope shape:

Success:

{ "ok": true, "data": {...}, "meta": { "schema_version", "cli_version", "latency_ms" } }

Partial success (batch):

{ "ok": "partial", "data": { "succeeded": [...], "failed": [...] }, "meta": {...} }

Error:

{ "ok": false, "error": { "code", "message", "retryable", ... }, "meta": {...} }

用户需求	操作类型	命令
查询某期刊的IF	读取	`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`
查看子命令的Schema	读取	`python3 journal_if.py schema lookup`

Exit codes

输出格式

Code	Meaning
`0`	success (including partial success)
`1`	runtime / upstream error
`2`	validation / bad input (missing file, bad flag)
`3`	not found (no journal matched)

当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": {...} }

Error codes (inside

error.code

)

退出码

Code	Retryable	Exit	Meaning
`not_found`	no	3	Lookup completed but no source matched
`upstream_unavailable`	yes	1	OpenAlex API failed transiently; retry later or use `--offline`
`file_not_found`	no	2	Input file path does not exist
`validation_error`	no	2	Bad argument or flag combination
`runtime_error`	yes	1	Unexpected internal error

编码	含义
`0`	成功（含部分成功）
`1`	运行时/上游服务错误
`2`	校验失败/输入错误（文件缺失、参数无效）
`3`	未找到匹配的期刊

Data Sources

错误码（位于

error.code

字段内）

Bundled CSV — ~200 top journals across life sciences, medicine, chemistry, physics, and engineering. Curated from JCR data, shipped with the skill. Always available, instant.
OpenAlex API — Free, open API that computes an approximate 2-year impact factor from citation counts. Covers virtually all academic journals. The number differs from the official JCR IF — it's a citation-rate metric computed from the same formula (citations in year Y to items published in Y-1 and Y-2, divided by citable items in those two years) but using OpenAlex's own article classification. Adequate for ranking and comparison; do not cite as "the JCR impact factor" in formal contexts.

编码	可重试	退出码	含义
`not_found`	否	3	查询完成但无匹配数据源
`upstream_unavailable`	是	1	OpenAlex API临时故障，请稍后重试或使用 `--offline` 模式
`file_not_found`	否	2	输入文件路径不存在
`validation_error`	否	2	参数或参数组合无效
`runtime_error`	是	1	意外的内部错误

When to use which

数据源

Scenario	Source
Quick check of a major journal	Bundled CSV (instant)
Niche or newer journal	OpenAlex fallback (automatic)
Formal submission / grant	Note: OpenAlex IF ≠ official JCR IF. Cite only as approximate.
Batch processing many journals	CSV for cached ones, OpenAlex for misses
Offline / air-gapped	`--offline` flag (bundled CSV only)

内置CSV — 涵盖生命科学、医学、化学、物理、工程领域的约200种顶级期刊，基于JCR数据整理，随技能内置，始终可用且查询即时。
OpenAlex API — 免费开放的API，基于引用计数计算近似的2年期影响因子，几乎覆盖所有学术期刊。其数值与官方JCR IF不同——虽然采用相同的计算公式（Y年对Y-1和Y-2年发表文献的引用数，除以这两年的可引用文献数），但使用OpenAlex自身的文章分类体系。适用于排名和对比，请勿在正式场景中作为「JCR影响因子」引用。

Workflow

各数据源适用场景

Step 1: Detect Intent

—

Intent	Action
"What's the IF of Nature?"	`lookup "Nature"`
"Compare IF of Cell and Science"	Run `lookup` twice, compare results
"Which immunology journals have IF > 20?"	`search "immunology"` then filter
"Process this list of journals"	`batch journals.txt`
"Is this a high-impact journal?"	`lookup` then interpret IF in field context

场景	数据源
快速查询主流期刊	内置CSV（即时返回）
小众或新期刊	OpenAlex兜底（自动切换）
正式投稿/基金申请	注意：OpenAlex IF ≠ 官方JCR IF，仅可作为近似值引用
批量处理大量期刊	缓存期刊用CSV，未命中则用OpenAlex
离线/物理隔离环境	使用 `--offline` 参数（仅内置CSV）

Step 2: Execute

工作流程

—

步骤1：识别意图

Run the appropriate

journal_if.py

command. The script handles:

Local CSV lookup (instant, ~200 curated journals)
OpenAlex API fallback (automatic, approximate 2-year IF)
Fuzzy matching — catches minor name variations

用户意图	操作
「Nature的IF是多少？」	`lookup "Nature"`
「对比Cell和Science的IF」	运行两次 `lookup` ，对比结果
「哪些免疫学期刊的IF大于20？」	先 `search "immunology"` 再筛选
「处理这个期刊列表」	`batch journals.txt`
「这是一本高影响因子期刊吗？」	先 `lookup` ，再结合领域背景解读IF

Step 3: Present Results

步骤2：执行

Show the journal name, impact factor, and data year
Note the source (CSV cache vs OpenAlex approximate)
For search results: show a table with IF, year, and category

运行对应的

journal_if.py

命令。脚本会自动处理：

本地CSV查询（即时返回，约200种精选期刊）
OpenAlex API兜底（自动切换，提供近似2年期IF）
模糊匹配 — 可处理期刊名称的微小差异

Understanding Impact Factor

步骤3：展示结果

IF Range	Typical Tier	Example
> 30	Elite (top 0.1%)	Nature (64.8), Science (56.9), Cell (64.5)
20–30	Exceptional (top 1%)	Cancer Cell (50.3), Immunity (32.4)
10–20	Excellent (top 5%)	Nature Communications (16.6), Sci Adv (13.6)
5–10	Strong (top 15%)	eLife (7.7), Cell Reports (8.8)
2–5	Solid	PLOS ONE (3.7), Sci Rep (4.6)
< 2	Niche / new	Many field-specific and new journals

Caveats:

IF varies dramatically by field — a top mathematics journal may have IF < 5 while a mid-tier oncology journal has IF > 10.
Always compare IF within the same field.
The IF data year matters; values shift annually.
OpenAlex approximate IF differs from official JCR IF; treat as a ranking metric, not a certified number.

展示期刊名称、影响因子和数据年份
注明数据来源（CSV缓存 vs OpenAlex近似值）
搜索结果：以表格形式展示IF、年份和分类

Batch Processing

影响因子解读

Create a text file with one journal name per line:

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

Then run:

bash

python3 journal_if.py batch journals.txt

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存在差异，仅可作为排名参考，而非认证数值。

Troubleshooting

批量处理

Issue	Solution
"No data found"	Try a shorter/alternative name; use `search` for fuzzy matching
OpenAlex returns 0 or None IF	The journal may be too new (needs 2+ years of data); use `--offline` to check cache only
OpenAlex IF differs from JCR	Expected — OpenAlex uses its own article classification. Use for ranking, not formal citation.
Cache download fails	Check network; the bundled CSV still works offline
Wrong journal matched	Use more specific name; the fuzzy matcher picks the closest substring match

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

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

然后运行：

bash

python3 journal_if.py batch journals.txt

—

故障排查

—

问题	解决方案
「未找到数据」	尝试更短的名称或别名；使用 `search` 进行模糊匹配
OpenAlex返回的IF为0或None	该期刊可能过于新（需要至少2年的数据）；使用 `--offline` 仅检查缓存
OpenAlex IF与JCR不一致	属于正常情况——OpenAlex使用自身的文章分类体系，仅可用于排名，不可正式引用
缓存下载失败	检查网络连接；内置CSV仍可离线使用
匹配到错误的期刊	使用更具体的名称；模糊匹配会选择最接近的子串匹配项

journal-if

Original

Translation

Journal Impact Factor Lookup

Quick Reference

期刊影响因子查询

Output format

快速参考

Exit codes

输出格式

Error codes (inside
`error.code`
)

退出码

Data Sources

错误码（位于
`error.code`
字段内）

When to use which

数据源

Workflow

各数据源适用场景

Step 1: Detect Intent

Step 2: Execute

工作流程

步骤1：识别意图

Step 3: Present Results

步骤2：执行

Understanding Impact Factor

步骤3：展示结果

Batch Processing

影响因子解读

Troubleshooting

批量处理

故障排查

journal-if

Original

Translation

Journal Impact Factor Lookup

Quick Reference

期刊影响因子查询

Output format

快速参考

Exit codes

输出格式

Error codes (inside error.code)

退出码

Data Sources

错误码（位于error.code字段内）

When to use which

数据源

Workflow

各数据源适用场景

Step 1: Detect Intent

Step 2: Execute

工作流程

步骤1：识别意图

Step 3: Present Results

步骤2：执行

Understanding Impact Factor

步骤3：展示结果

Batch Processing

影响因子解读

Troubleshooting

批量处理

故障排查

Error codes (inside
`error.code`
)

错误码（位于
`error.code`
字段内）