journal-abbrev

雑誌略称の検索

複数ソースを順に検索して、学術誌・雑誌名の略称を調べます。JabRef データベース（約 25K 誌）→ AbbrevISO API（ISO 4）→ NLM Catalog（MEDLINE）の順に検索します。

重要なルール： 検索には必ず jabbrv.py を使用してください。一般的な学術誌であっても、略称を推測してはいけません。

クイックリファレンス

ユーザーの要望...	階層	コマンド
学術誌名を略称にする	read	python3 jabbrv.py abbrev "Nature Medicine"
略称を正式名称に展開する	read	python3 jabbrv.py expand "Nat. Med."
方向を自動判定する	read	python3 jabbrv.py lookup "J. Am. Chem. Soc."
あいまい検索（ページ分割）	read	python3 jabbrv.py search "biolog chem" --limit 10 --offset 0
.bib ファイルを処理する	write	python3 jabbrv.py bib refs.bib
.bib の変更をプレビューする（書き込みなし）	read	python3 jabbrv.py bib refs.bib --dry-run
.bib の出力先を明示する	write	python3 jabbrv.py bib refs.bib --output out.bib
.bib の略称を展開する	write	python3 jabbrv.py bib refs.bib --expand
再実行安全な .bib（再試行時にキャッシュ済みのエンベロープを返す）	write	python3 jabbrv.py bib refs.bib --idempotency-key run-001
テキストリストを一括処理する	read	python3 jabbrv.py batch journals.txt
NDJSON ストリームとして一括処理する	read	python3 jabbrv.py batch journals.txt --stream
キャッシュの状態を確認する	read	python3 jabbrv.py cache status
不足しているキャッシュファイルをダウンロードする	write	python3 jabbrv.py cache update
更新で取得される内容をプレビューする	read	python3 jabbrv.py cache update --dry-run
アトミックに再構築する	⚠️ 破壊的	python3 jabbrv.py cache rebuild --yes
再構築をプレビューする（削除なし）	read	python3 jabbrv.py cache rebuild --dry-run
stderr への進行状況出力を抑制する	read	python3 jabbrv.py --quiet cache update
CLI の機械可読な仕様	read	python3 jabbrv.py schema
1 つのサブコマンドのスキーマ	read	python3 jabbrv.py schema lookup

出力形式

CLI がターミナルに接続されていない場合（パイプ経由、またはエージェントによるキャプチャ時）、標準出力は安定した 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": {...} }

終了コード

コード	意味
0	成功（部分的な成功を含む）
1	実行時エラー／上流エラー
2	検証エラー／不正な入力（ファイルが見つからない、フラグが不正）
3	見つからない（検索対象の学術誌が存在しない）

エラーコード（error.code 内）

コード	再試行可能	終了	意味
not_found	いいえ	3	検索は完了しましたが、一致するソースがありませんでした
upstream_unavailable	はい	1	1 つ以上の上流 API で一時的な障害が発生したため、検索を完了できませんでした。各障害を示す error.sources[] が含まれます。後で再試行してください。
file_not_found	いいえ	2	入力ファイルのパスが存在しません
validation_error	いいえ	2	引数またはフラグの組み合わせが不正です
runtime_error	はい	1	予期しない内部エラー

終了コードだけでなく、error.code と error.retryable を基に分岐してください。終了コード 1 は、upstream_unavailable と runtime_error の両方に該当します。機械可読な完全な一覧：python3 jabbrv.py schema → data.error_codes。

環境変数（ホストが設定。エージェントの argv では設定しません）

変数	効果
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 が含まれ、呼び出し元はポリシーを確認できます。

信頼境界：これらは引数ではなく、プロセス環境から読み取られます。ホストまたはサンドボックスが設定し、エージェントは argv から上書きできません。スキーマのイントロスペクション：python3 jabbrv.py schema → data.global_env。

再試行、冪等性、破壊的な操作の意図

• 終了コードだけではなく、error.code と error.retryable に基づいて分岐してください。終了コード 1 は upstream_unavailable（再試行）と runtime_error（1 回再試行してからエスカレーション）の両方を表します。
• bib --idempotency-key <token> は、出力ファイルの隣に成功エンベロープを <output>.<token>.envelope.json として保存します。同じキーで再試行すると、書き換えを再実行せず、meta.idempotent_replay: true を伴うそのエンベロープを返します。トークンは [A-Za-z0-9._-]{1,64} に一致する必要があります。
• cache rebuild はアトミックです。ダウンロードは隣接ディレクトリにステージングされ、すべてのファイルが成功した場合にのみ切り替えが行われます。いずれかが失敗した場合、既存のキャッシュは保持され、レスポンスは再試行可能な upstream_unavailable になります。監査ポリシー向けに meta.confirmed: true を記録するには --yes を追加してください。CLI 自体はプロンプトを表示しないため、--yes は実行条件ではありません。

ワークフロー

ステップ 1：意図を判定する

意図	アクション
ジャーナル名または略称が 1 つ	lookup（自動判定）、または abbrev／expand（方向を明示）を使用
「X の略称は何ですか？」	abbrev を使用
「X はどのジャーナルですか？」	expand を使用
不完全または曖昧な名前	あいまい検索には search を使用
.bib ファイル内のジャーナル名を修正	bib を使用
処理するジャーナルのリスト	batch を使用

ステップ 2：実行する

適切な jabbrv.py コマンドを実行します。スクリプトは次の処理を行います。

1. ローカルキャッシュの検索（即時、JabRef の約 25K 件のジャーナル）
2. AbbrevISO API によるフォールバック（アルゴリズムによる ISO 4 略称生成、順方向のみ）
3. NLM Catalog によるフォールバック（生物医学系ジャーナル、双方向）

初回実行時に、JabRef の CSV キャッシュファイルが自動的にダウンロードされます（約 2～5 MB）。

ステップ 3：結果を提示する

• 正式名称、略称、情報源をすべて提示します
• 該当する場合は規格（ISO 4 または MEDLINE）を明記します
• .bib の処理では、確定前に変更の概要を提示します

ISO 4 と MEDLINE

一般的な略称規格は 2 種類あります。

規格	ピリオド	例	使用者
ISO 4	あり	Nat. Med.	ほとんどの出版社、BibTeX
MEDLINE	なし	Nat Med	PubMed、NLM データベース

JabRef は ISO 4 形式を提供します。NLM Catalog は MEDLINE 形式を提供します。AbbrevISO は LTWA（タイトル語略称リスト）から ISO 4 形式をアルゴリズムで計算します。

一般的な略称パターン

単語	略称	単語	略称
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.

注：「Nature」「Science」「Cell」などの単語 1 つだけのタイトルは、ISO 4 の規則に従い略称にしません。

統合例

Zotero との連携

# Export BibTeX from Zotero, then standardize journal names
zot export COLLECTION_KEY --format bibtex > refs.bib
python3 jabbrv.py bib refs.bib

LaTeX を使用する場合

# Before compiling, ensure all journal names are abbreviated
python3 jabbrv.py bib references.bib
# Use the output file (references_abbrev.bib) in your LaTeX document

バッチ処理

ジャーナル名を 1 行に 1 つずつ記載したテキストファイルを作成します。

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

次に、以下を実行します。

python3 jabbrv.py batch journals.txt

トラブルシューティング

問題	解決策
「結果が見つかりません」	部分一致検索を行うには、search に名前の一部を指定してください
キャッシュのダウンロードに失敗する	ネットワーク接続を確認し、cache update を再試行してください（強制的に更新するには cache rebuild を実行してください）
略称のスタイルが違う	JabRef = ISO 4（ピリオドあり）、NLM = MEDLINE（ピリオドなし）
BibTeX フィールドが検出されない	書式が journal = {Name}（波括弧）になっていることを確認してください