journal-abbrev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Journal Abbreviation Lookup

—

Look up journal/magazine name abbreviations using a multi-source cascade: JabRef database (~25K journals) → AbbrevISO API (ISO 4) → NLM Catalog (MEDLINE).

Critical rule: Always use

jabbrv.py

for lookups. Never guess abbreviations — even common journals have non-obvious abbreviations.

Claude Code 字段在上，OpenClaw/SkillsMP 字段在下 --- author: Agents365-ai category: Academic Research version: 1.3.0 created: 2026-03-29 updated: 2026-05-19 github: https://github.com/Agents365-ai/journal-abbrev homepage: https://github.com/Agents365-ai/journal-abbrev metadata: openclaw: requires: bins: - python3 emoji: "📖" homepage: https://github.com/Agents365-ai/journal-abbrev os: ["macos", "linux", "windows"]

Quick Reference

期刊缩写查询

User wants...	Command
Abbreviate a journal name	`python3 jabbrv.py abbrev "Nature Medicine"`
Expand an abbreviation	`python3 jabbrv.py expand "Nat. Med."`
Auto-detect direction	`python3 jabbrv.py lookup "J. Am. Chem. Soc."`
Fuzzy search (paginated)	`python3 jabbrv.py search "biolog chem" --limit 10 --offset 0`
Process a .bib file	`python3 jabbrv.py bib refs.bib`
Preview .bib changes (no write)	`python3 jabbrv.py bib refs.bib --dry-run`
Explicit .bib output path	`python3 jabbrv.py bib refs.bib --output out.bib`
Expand .bib abbreviations	`python3 jabbrv.py bib refs.bib --expand`
Replay-safe .bib (retry returns cached envelope)	`python3 jabbrv.py bib refs.bib --idempotency-key run-001`
Batch text list	`python3 jabbrv.py batch journals.txt`
Batch as NDJSON stream	`python3 jabbrv.py batch journals.txt --stream`
Inspect cache state	`python3 jabbrv.py cache status`
Download missing cache files	`python3 jabbrv.py cache update`
Preview what update would fetch	`python3 jabbrv.py cache update --dry-run`
Atomic rebuild (destructive, with audit marker)	`python3 jabbrv.py cache rebuild --yes`
Preview rebuild (no delete)	`python3 jabbrv.py cache rebuild --dry-run`
Suppress stderr progress	`python3 jabbrv.py --quiet cache update`
Machine-readable CLI contract	`python3 jabbrv.py schema`
Schema for one subcommand	`python3 jabbrv.py schema lookup`

通过多源级联查询期刊/杂志名称缩写：JabRef 数据库（约25000种期刊）→ AbbrevISO API（ISO 4标准）→ NLM Catalog（MEDLINE标准）。

重要规则： 必须使用

jabbrv.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 table/indented view when run on a TTY. To force a format:

--format json|table|human|auto

--json

remains as a back-compat alias for

--format json

. Flags may appear before or after the subcommand.

Envelope shape (always the same fields for every subcommand):

Success:

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

Partial success (batch):

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

Error:

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

用户需求...	命令
缩写期刊名称	`python3 jabbrv.py abbrev "Nature Medicine"`
展开缩写	`python3 jabbrv.py expand "Nat. Med."`
自动检测转换方向	`python3 jabbrv.py lookup "J. Am. Chem. Soc."`
模糊搜索（分页）	`python3 jabbrv.py search "biolog chem" --limit 10 --offset 0`
处理.bib文件	`python3 jabbrv.py bib refs.bib`
预览.bib文件修改（不写入）	`python3 jabbrv.py bib refs.bib --dry-run`
指定.bib输出路径	`python3 jabbrv.py bib refs.bib --output out.bib`
展开.bib文件中的缩写	`python3 jabbrv.py bib refs.bib --expand`
可重放的.bib处理（重试返回缓存结果）	`python3 jabbrv.py bib refs.bib --idempotency-key run-001`
批量处理文本列表	`python3 jabbrv.py batch journals.txt`
以NDJSON流形式批量处理	`python3 jabbrv.py batch journals.txt --stream`
查看缓存状态	`python3 jabbrv.py cache status`
下载缺失的缓存文件	`python3 jabbrv.py cache update`
预览缓存更新将获取的内容	`python3 jabbrv.py cache update --dry-run`
原子重建缓存（破坏性操作，带审计标记）	`python3 jabbrv.py cache rebuild --yes`
预览缓存重建（不删除现有缓存）	`python3 jabbrv.py cache rebuild --dry-run`
抑制stderr进度输出	`python3 jabbrv.py --quiet cache update`
机器可读CLI契约	`python3 jabbrv.py schema`
单个子命令的Schema	`python3 jabbrv.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 (the looked-up journal does not exist)

当CLI未连接到终端（通过管道传输或被Agent捕获）时，标准输出为稳定的JSON包；在TTY上运行时则显示人类可读的表格/缩进视图。可通过

--format json|table|human|auto

强制指定格式。

--json

作为

--format json

的向后兼容别名仍然有效。参数可在子命令之前或之后出现。

包结构（每个子命令的字段始终一致）：

成功：

{ "ok": true, "data": ..., "meta": { "schema_version", "cli_version", "cache", "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	One or more upstream APIs failed transiently; the lookup could not be concluded. Carries `error.sources[]` listing each failure. Retry later.
`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

Branch on

error.code

error.retryable

rather than exit code alone — exit

covers both

upstream_unavailable

and

runtime_error

. Full machine-readable listing:

python3 jabbrv.py schema

→

data.error_codes

代码	含义
`0`	成功（包括部分成功）
`1`	运行时/上游错误
`2`	验证/输入错误（文件缺失、参数错误）
`3`	未找到（查询的期刊不存在）

Environment variables (set by host, not by agent argv)

错误代码（位于

error.code

中）

Variable	Effect
`JABBRV_CACHE_DIR`	Override the cache directory (default: `<install>/cache` ). Useful in sandboxes where the install tree is read-only.
`JABBRV_OFFLINE`	Truthy ( `1` / `true` / `yes` / `on` ) skips AbbrevISO and NLM; only the local JabRef cache is consulted. Misses become definitive `not_found` (not retryable) since the host has declared upstream off-limits. `meta.offline: true` appears in every envelope so callers can see the policy.
`NO_COLOR`	https://no-color.org convention. Any non-empty value disables color. No ANSI is emitted today; `meta.no_color: true` appears when set so callers can see the policy.

Trust boundary: these are read from the process environment, not from arguments. The host or sandbox sets them; the agent cannot override them via argv. Schema introspection:

python3 jabbrv.py schema

→

data.global_env

代码	是否可重试	退出码	含义
`not_found`	否	3	查询完成但无匹配源
`upstream_unavailable`	是	1	一个或多个上游API临时失败；查询无法完成。包含 `error.sources[]` 列出每个失败项。稍后重试。
`file_not_found`	否	2	输入文件路径不存在
`validation_error`	否	2	参数或标志组合错误
`runtime_error`	是	1	意外的内部错误

应根据

error.code

error.retryable

进行分支判断，而非仅依赖退出码——退出码

涵盖

upstream_unavailable

（可重试）和

runtime_error

（重试一次后升级）。完整的机器可读列表：

python3 jabbrv.py schema

→

data.error_codes

。

Retries, idempotency, and destructive intent

环境变量（由主机设置，而非Agent的argv参数）

Branch on
error.code
+
error.retryable
, not exit code alone. Exit
```
1
```
covers both
```
upstream_unavailable
```
(retry) and
```
runtime_error
```
(retry once, then escalate).
bib --idempotency-key <token>
persists the success envelope next to the output file as
```
<output>.<token>.envelope.json
```
. A retry with the same key returns that envelope with
```
meta.idempotent_replay: true
```
instead of rerunning the rewrite. Token must match
```
[A-Za-z0-9._-]{1,64}
```
.
cache rebuild
is atomic — downloads stage into a sibling directory and the swap only happens if every file succeeded. If any fails, the existing cache is preserved and the response is
```
upstream_unavailable
```
(retryable). Add
```
--yes
```
to record
```
meta.confirmed: true
```
for audit policies; the CLI itself never prompts, so
```
--yes
```
is not a gate.

变量	作用
`JABBRV_CACHE_DIR`	覆盖缓存目录（默认： `<install>/cache` ）。在安装目录为只读的沙箱环境中非常有用。
`JABBRV_OFFLINE`	真值（ `1` / `true` / `yes` / `on` ）会跳过AbbrevISO和NLM；仅使用本地JabRef缓存。由于主机已声明上游不可用，未命中将被判定为确定的 `not_found` （不可重试）。每个包中都会显示 `meta.offline: true` ，以便调用方了解此策略。
`NO_COLOR`	遵循https://no-color.org约定。任何非空值都会禁用颜色。目前不会输出ANSI代码；设置后包中会显示`meta.no_color: true`，以便调用方了解此策略。

信任边界：这些变量从进程环境读取，而非从参数读取。由主机或沙箱设置；Agent无法通过argv覆盖。Schema自省：

python3 jabbrv.py schema

→

data.global_env

。

Workflow

重试、幂等性与破坏性操作

Step 1: Detect Intent

—

Intent	Action
Single journal name/abbreviation	Use `lookup` (auto-detect) or `abbrev` / `expand` (explicit direction)
"What's the abbreviation for X?"	Use `abbrev`
"What journal is X?"	Use `expand`
Partial or uncertain name	Use `search` for fuzzy matching
Fix journal names in .bib file	Use `bib`
List of journals to process	Use `batch`

根据
error.code
+
error.retryable
进行分支判断，而非仅依赖退出码。退出码
```
1
```
涵盖
```
upstream_unavailable
```
（可重试）和
```
runtime_error
```
（重试一次后升级）。
bib --idempotency-key <token>
会将成功包持久化到输出文件旁边，命名为
```
<output>.<token>.envelope.json
```
。使用相同密钥重试时，会返回该包并标记
```
meta.idempotent_replay: true
```
，而非重新执行重写操作。令牌必须匹配
```
[A-Za-z0-9._-]{1,64}
```
格式。
cache rebuild
是原子操作——下载的文件会先存储到同级目录，只有当所有文件下载成功时才会替换现有缓存。如果有任何失败，现有缓存会被保留，响应为
```
upstream_unavailable
```
（可重试）。添加
```
--yes
```
参数会在包中记录
```
meta.confirmed: true
```
以满足审计策略；CLI本身不会弹出提示，因此
```
--yes
```
并非必要的确认步骤。

Step 2: Execute

工作流程

—

步骤1：识别意图

Run the appropriate

jabbrv.py

command. The script handles:

Local cache lookup (instant, ~25K journals from JabRef)
AbbrevISO API fallback (algorithmic ISO 4 abbreviation, forward only)
NLM Catalog fallback (biomedical journals, bidirectional)

First run downloads JabRef CSV cache files automatically (~2-5 MB).

意图	操作
单个期刊名称/缩写转换	使用 `lookup` （自动检测）或 `abbrev` / `expand` （指定方向）
“X的缩写是什么？”	使用 `abbrev`
“X是哪本期刊？”	使用 `expand`
名称不完整或不确定	使用 `search` 进行模糊匹配
修复.bib文件中的期刊名称	使用 `bib`
处理期刊列表	使用 `batch`

Step 3: Present Results

步骤2：执行命令

Show the full name, abbreviation, and source
Note the standard (ISO 4 vs MEDLINE) when relevant
For .bib processing: show the change summary before confirming

运行相应的

jabbrv.py

命令。脚本会处理以下步骤：

本地缓存查询（即时响应，来自JabRef的约25000种期刊）
AbbrevISO API 回退（基于算法的ISO 4缩写，仅支持正向转换）
NLM Catalog 回退（生物医学期刊，支持双向转换）

首次运行时会自动下载JabRef CSV缓存文件（约2-5 MB）。

ISO 4 vs MEDLINE

步骤3：展示结果

Two common abbreviation standards exist:

Standard	Periods	Example	Used by
ISO 4	Yes	Nat. Med.	Most publishers, BibTeX
MEDLINE	No	Nat Med	PubMed, NLM databases

JabRef provides ISO 4 style. NLM Catalog provides MEDLINE style. AbbrevISO computes ISO 4 algorithmically from LTWA (List of Title Word Abbreviations).

显示全名、缩写及来源
必要时注明标准（ISO 4 vs MEDLINE）
处理.bib文件时：确认前先显示修改摘要

Common Abbreviation Patterns

ISO 4 vs MEDLINE

Word	Abbreviation	Word	Abbreviation
Journal	J.	International	Int.
American	Am.	European	Eur.
Science/Sciences	Sci.	Medicine/Medical	Med.
Biology/Biological	Biol.	Chemistry/Chemical	Chem.
Physics/Physical	Phys.	Engineering	Eng.
Research	Res.	Review/Reviews	Rev.
Society	Soc.	National	Natl.
Proceedings	Proc.	Transactions	Trans.
Letters	Lett.	Communications	Commun.
Applied	Appl.	Computational	Comput.

Note: Single-word titles (e.g., "Nature", "Science", "Cell") are NOT abbreviated per ISO 4 rules.

存在两种常见的缩写标准：

标准	是否带句点	示例	使用场景
ISO 4	是	Nat. Med.	大多数出版商、BibTeX
MEDLINE	否	Nat Med	PubMed、NLM数据库

JabRef提供ISO 4格式。NLM Catalog提供MEDLINE格式。AbbrevISO基于LTWA（标题词缩写列表）通过算法计算ISO 4缩写。

Integration Examples

常见缩写模式

With Zotero

—

bash

undefined

单词	缩写	单词	缩写
Journal	J.	International	Int.
American	Am.	European	Eur.
Science/Sciences	Sci.	Medicine/Medical	Med.
Biology/Biological	Biol.	Chemistry/Chemical	Chem.
Physics/Physical	Phys.	Engineering	Eng.
Research	Res.	Review/Reviews	Rev.
Society	Soc.	National	Natl.
Proceedings	Proc.	Transactions	Trans.
Letters	Lett.	Communications	Commun.
Applied	Appl.	Computational	Comput.

注意： 根据ISO 4规则，单字标题（如“Nature”“Science”“Cell”）不进行缩写。

Export BibTeX from Zotero, then standardize journal names

集成示例

—

与Zotero集成

zot export COLLECTION_KEY --format bibtex > refs.bib python3 jabbrv.py bib refs.bib

undefined

bash

undefined

With LaTeX

从Zotero导出BibTeX，然后标准化期刊名称

bash

undefined

zot export COLLECTION_KEY --format bibtex > refs.bib python3 jabbrv.py bib refs.bib

undefined

Before compiling, ensure all journal names are abbreviated

与LaTeX集成

python3 jabbrv.py bib references.bib

bash

undefined

Use the output file (references_abbrev.bib) in your LaTeX document

编译前，确保所有期刊名称已缩写

undefined

python3 jabbrv.py bib references.bib

Batch Processing

在LaTeX文档中使用输出文件（references_abbrev.bib）

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 jabbrv.py batch journals.txt

undefined

Troubleshooting

批量处理

Issue	Solution
"No result found"	Try `search` with partial name for fuzzy matching
Cache download fails	Check network connection, retry with `cache update` (or `cache rebuild` to force)
Wrong abbreviation style	JabRef = ISO 4 (with dots), NLM = MEDLINE (no dots)
BibTeX field not detected	Ensure format is `journal = {Name}` (curly braces)

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

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

然后运行：

bash

python3 jabbrv.py batch journals.txt

—

故障排除

—

问题	解决方案
“未找到结果”	使用 `search` 命令并输入部分名称进行模糊匹配
缓存下载失败	检查网络连接，使用 `cache update` 重试（或 `cache rebuild` 强制重建）
缩写格式错误	JabRef = ISO 4（带句点），NLM = MEDLINE（无句点）
BibTeX字段未被检测到	确保格式为 `journal = {Name}` （使用大括号）

journal-abbrev

Original

Translation

Journal Abbreviation Lookup

Quick Reference

期刊缩写查询

Output format

快速参考

Exit codes

输出格式

Error codes (inside error.code)

退出码

Environment variables (set by host, not by agent argv)

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

Retries, idempotency, and destructive intent

环境变量（由主机设置，而非Agent的argv参数）

Workflow

重试、幂等性与破坏性操作

Step 1: Detect Intent

Step 2: Execute

工作流程

步骤1：识别意图

Step 3: Present Results

步骤2：执行命令

ISO 4 vs MEDLINE

步骤3：展示结果

Common Abbreviation Patterns

ISO 4 vs MEDLINE

Integration Examples

常见缩写模式

With Zotero

Export BibTeX from Zotero, then standardize journal names

集成示例

与Zotero集成

With LaTeX

从Zotero导出BibTeX，然后标准化期刊名称

Before compiling, ensure all journal names are abbreviated

与LaTeX集成

Use the output file (references_abbrev.bib) in your LaTeX document

编译前，确保所有期刊名称已缩写

Batch Processing

在LaTeX文档中使用输出文件（references_abbrev.bib）

Troubleshooting

批量处理

故障排除

Error codes (inside
`error.code`
)

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