菜单
Word文書(.docx)内のプレーンテキスト文献番号をEndNoteフィールドコードに変換する。PubMed APIから書誌情報を取得し、OOXMLフィールドコードを生成してマーカーを置換する。EndNoteスタイル変更時の句読点・スペース位置の一括修正（方向A/B）にも対応。トリガー: EndNoteフィールド挿入, 文献番号をEndNoteに変換, 句読点位置修正, /endnote-insert
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
| name | endnote-insert |
| description | Word文書(.docx)内のプレーンテキスト文献番号をEndNoteフィールドコードに変換する。PubMed APIから書誌情報を取得し、OOXMLフィールドコードを生成してマーカーを置換する。EndNoteスタイル変更時の句読点・スペース位置の一括修正（方向A/B）にも対応。トリガー: EndNoteフィールド挿入, 文献番号をEndNoteに変換, 句読点位置修正, /endnote-insert |
Word文書内のプレーンテキスト文献マーカー（例: (4), (11)）を、EndNoteが認識するフィールドコードに自動変換する。EndNoteスタイル変更時の句読点・スペース位置調整にも対応。
関連ツール: PubMedを見ながら1件ずつ対話的に引用を挿入する場合は、Chrome拡張 PubMed2EndNote（https://github.com/matsuikentaro1/pubmed2endnote）を使う。拡張機能はWordフレーバーHTMLをクリップボード経由で貼り付ける方式、本スキルはdocxのXMLを直接編集する方式で、「docx内の多数マーカーの一括変換」は本スキルの担当。
scripts/endnote_inserter.py の __main__ ブロックを編集まずプロジェクトフォルダ内にCSVファイルがないか確認する。
Glob pattern: **/*.csv
CSVが見つかった場合:
PubMed_ID 列（または類似の列名）があるか確認する_tmp_refs_*.csv が残っている場合、マージ未完了の可能性が高い。処理を中断し、codex-refsのマージ手順を先に実行するようユーザーに報告するCSVがない場合、またはCSVにPMID情報がない場合:
過去にLLMがPMIDを「記憶」から捏造し、完全に間違った論文がEndNoteフィールドに挿入される重大事故が発生した。以下のルールを絶対に守ること。
{'pmid': '37275982', 'marker': '[6]'}, # refs.csv row 4 のように、どのCSVの何行目から取得したかを書く。出典コメントを書けないPMIDは使用禁止PubMedに収録されていない文献（FDA通知、行政文書、和文論文等）はスクリプトでは処理できない。対象から除外し、手動対応が必要な旨をユーザーに伝える。
スクリプトは以下の環境変数を参照する。初回使用時にユーザーへ設定を案内すること。
| 環境変数 | 必須 | 説明 |
|---|---|---|
NCBI_EMAIL | 必須 | NCBI 利用ポリシーで求められる連絡先メールアドレス。未設定だとスクリプトがエラー終了する |
ENDNOTE_DB_ID | 任意 | EndNoteライブラリの db-id。未設定時はデフォルト値を使用 |
設定例（Windows）:
set NCBI_EMAIL=user@example.com
scripts/endnote_inserter.py をプロジェクトフォルダにコピーし、__main__ ブロックを編集する。
編集箇所:
entries リストにマーカーとPMIDの対応を記載input_docx と output_docx のパスを設定ENDNOTE_DB_ID を対象EndNoteライブラリのdb-idに変更（環境変数でも指定可）db-idの取得方法: docxをzipとして展開し、word/document.xml 内で db-id= を検索する。既存のEndNoteフィールドがない場合は任意の値でよい。
python endnote_inserter.py
各文献について以下が出力される:
報告する内容:
1箇所に複数文献を引用するマーカー（例: [PMID 33150256; 37041858] や (1, 2) や (3-5)）は、multi-cite XML（<EndNote><Cite>...<Cite>...</EndNote>）を使わず、各PMIDごとに独立した EndNoteフィールドを生成し、スペースを空けずに隣接させる。
<!-- ✅ 正しい: 個別フィールドをスペースなしで隣接 -->
<w:r><w:fldChar w:fldCharType="begin"/></w:r>
... ADDIN EN.CITE <文献A> ...
<w:r><w:fldChar w:fldCharType="end"/></w:r><w:r><w:fldChar w:fldCharType="begin"/></w:r>
... ADDIN EN.CITE <文献B> ...
<w:r><w:fldChar w:fldCharType="end"/></w:r>
理由: Word で EndNoteの「Update Citations and Bibliography」を実行すると、隣接するフィールドが自動的に結合されて (1, 2) のように表示される。multi-cite XML を手作りすると構造が複雑になりバグの原因になるが、個別フィールドの隣接なら build_field_xml() をそのまま使えて安全。
実装パターン:
field_xml_parts = []
for pmid in pmids:
nbib = pmid_data[pmid]
en_xml = build_endnote_xml(nbib)
display = f'({first_author}, {year})'
field_xml_parts.append(build_field_xml(en_xml, display))
field_xml = ''.join(field_xml_parts) # スペースなしで結合
ET.tostring() が未使用の名前空間宣言を削除し、docxが破損する（30以上のxmlns:xx宣言が3つ程度に減る）。文字列ベースで直接編集するか、lxml を使う。if element: を使わず if element is not None: を使う — lxml 要素の真偽値は 子要素の有無 で判定される。<w:t>テキスト</w:t> は子要素がないため False と評価され、要素が見つかっているのにブロックがスキップされる重大バグになる。<w:r> 検索時は <w:rPr>, <w:rFonts> 等への誤マッチに注意。タグ名直後の文字をチェック。<w:br type="page"/>）の有無を確認 — 1つの <w:p> にページブレークと次ページの見出しが混在するケースがある。先頭テキストで識別して削除すると、後半の見出しまで消える。ページブレークを含む段落を削除する場合は split_para_at_pagebreak() で分離してから処理する（詳細は references/docx_xml_editing.md セクション7参照）。fetch_pubmed_xml() はNCBI利用ポリシー準拠の tool/email パラメータ付与と、429/5xx・タイムアウト時の自動リトライ（最大3回、待機1s→2s）を実装済み。ArticleIdList に無い場合 Article/ELocationID からフォールバック取得する（一部文献はELocationIDにしかDOIが無い）。ArticleDate[DateType=Electronic]（正式な電子出版日）を優先し、無ければ History の entrez date にフォールバックする。rettype=xml&retmode=xml）。MEDLINE テキスト形式（rettype=medline&retmode=text）はウムラウト等の Unicode 文字を ASCII に変換して返すため、Yücel → Yucel、Schröder → Schroder のような文字化けが発生する。endnote_inserter.py は fetch_pubmed_xml() / parse_pubmed_xml() を使用しており対応済み。問題: docx 内に文献リストを含めると、書誌情報中の巻号表記（例: Sleep medicine. 52(3):102-110 の (3)）が引用マーカーと誤マッチし、本来とは無関係の箇所にEndNoteフィールドが挿入される。
実例: 引用マーカー (3) を処理する際、巻号 52(3):... の (3) にも誤マッチして置換回数が増加した。
対策: 引用マーカー挿入前のdocxには文献リストを含めない。EndNoteが「Update Citations and Bibliography」で自動生成するため、手動リストは不要。
問題: Windowsで日本語を含むパスにあるdocxを操作する場合、Bashのコマンドラインに直接Pythonコードを書くと（python -c "..."）、パス文字列が文字化けして FileNotFoundError になることがある。
対策: 必ずスクリプトファイル（.py）に書き出してから実行する。
# ❌ 避ける
python -c "import zipfile; zipfile.ZipFile('C:\\日本語パス\\file.docx')"
# ✅ 正しい
# → スクリプトファイルに書き出してから実行
python script.py
Word の EndNote 引用には 2種類のフィールド形式がある。対象 docx を確認してからスクリプトを選択すること。
endnote_inserter.py が生成する標準形式。引用 XML は instrText に直接埋め込む。
<w:fldChar w:fldCharType="begin"/>
<w:instrText> ADDIN EN.CITE <EndNote>...</EndNote></w:instrText>
...
Word の新しい形式。引用 XML は fldChar の子要素 fldData に base64 エンコードして格納する。
<w:fldChar w:fldCharType="begin">
<w:fldData xml:space="preserve">PEVuZE5v...（base64）</w:fldData>
</w:fldChar>
<w:instrText> ADDIN EN.CITE.DATA </w:instrText> ← ただのラベル、中身なし
...
見分け方: document.xml 内で fldData タグを検索。あれば形式B。
形式Bの既存文献を修正する場合（過去プロジェクトで実績のある手順。専用スクリプトは同梱していないため、以下を参考に都度作成する）:
fldData の base64 をデコード → EndNote XML を取得fldData を置き換えdef b64_encode_flddata(xml_str: str) -> str:
raw = xml_str.encode('utf-8')
b64 = base64.b64encode(raw).decode('ascii')
lines = [b64[i:i+76] for i in range(0, len(b64), 76)]
return '\r\n'.join(lines) + '\r\n'
EndNote フィールドは内部に EN.CITE.DATA のネストされたフィールドを含む場合がある。フィールド境界を走査するときは depth（深さ）を追跡 し、トップレベルの begin/separate/end のみ を処理すること。depth を追跡せずに処理すると、ネストされた内側のフィールドを独立したフィールドと誤認して壊す。
field_depth = 0
for run in runs:
fld_type = get_fld_char_type(run)
if fld_type == 'begin':
field_depth += 1
if field_depth == 1:
... # トップレベル開始のみ処理
elif fld_type == 'separate':
if field_depth == 1:
... # トップレベルのみ処理
elif fld_type == 'end':
if field_depth == 1:
... # トップレベル終了のみ処理
field_depth -= 1
重要原則: フィールドの 表示テキスト（separate ～ end 間の <w:t>）は EndNote が「Update Citations and Bibliography」時に再生成するため、手動変更は上書きされる。スペース・句読点は必ず フィールド外（fldChar type="begin" より前、または type="end" より後の run）に配置する。
<!-- ❌ 悪い例: スペースがフィールド内 → 更新で消える -->
<w:r><w:t>productivity</w:t></w:r>
<w:r><w:fldChar w:fldCharType="begin"/></w:r>
...
<w:r><w:fldChar w:fldCharType="separate"/></w:r>
<w:r><w:t xml:space="preserve"> (Redeker et al., 2019)</w:t></w:r>
<w:r><w:fldChar w:fldCharType="end"/></w:r>
<!-- ✅ 正しい例: スペースがフィールド外 → 更新でも維持 -->
<w:r><w:t xml:space="preserve">productivity </w:t></w:r>
<w:r><w:fldChar w:fldCharType="begin"/></w:r>
...
<w:r><w:fldChar w:fldCharType="separate"/></w:r>
<w:r><w:t>(Redeker et al., 2019)</w:t></w:r>
<w:r><w:fldChar w:fldCharType="end"/></w:r>
EndNoteの出力スタイルを変更すると、引用番号と周囲の句読点・スペースの位置関係がずれる。方向A と 方向B の2パターンを使い分ける。
| 変更前 | 変更後 |
|---|---|
sleepiness,(1) | sleepiness (1), |
injuries.(3) | injuries (3). |
guidelines;(18) | guidelines (18); |
jetlag(4) | jetlag (4) |
操作: フィールド前の <w:t> 末尾から句読点を除去しスペースを付与 → フィールド後の <w:t> 先頭に句読点を挿入。
| 変更前 | 変更後 |
|---|---|
sleepiness (1), | sleepiness,(1) |
injuries (3). | injuries.(3) |
guidelines (18); | guidelines;(18) |
操作: フィールド後の <w:t> 先頭から句読点を除去 → フィールド前の <w:t> 末尾のスペースを除去し句読点を付与。
begin ～ end）は一切触らない（EndNoteが管理する領域）<w:t> を書き換えたら xml:space="preserve" を必ず設定（XML 名前空間は {http://www.w3.org/XML/1998/namespace}space）, . ; を必須とし、必要に応じて : ? 等を追加; は列挙的引用（例: guidelines;(18) ILO;(19)）で頻出するので忘れずに含める<w:vertAlign w:val="superscript"/>）の引用は句読点パターンが異なる可能性があるため、自動修正後に目視確認from lxml import etree
W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"
XML_SPACE = "{http://www.w3.org/XML/1998/namespace}space"
PUNCT_CHARS = (',', '.', ';')
# 段落ごとに「イベント列」を構築
# 1つの <w:r> 内に複数の <w:fldChar> が存在することがあるため、
# find() ではなく子要素を順に走査してフラット化する
events = []
for child in para:
if child.tag == f"{W}r":
for sub in child:
if sub.tag == f"{W}fldChar":
events.append(("fld", sub.get(f"{W}fldCharType"), child, sub))
elif sub.tag == f"{W}instrText":
events.append(("instr", sub.text or "", child, sub))
elif sub.tag == f"{W}t":
events.append(("text", sub.text or "", child, sub))
# 各 EN.CITE フィールドを depth 追跡で検出し、
# prev_t（直前の <w:t>）と after_t（直後の <w:t>）を特定して句読点を移動する
詳細な実装例・注意点は references/docx_xml_editing.md セクション9を参照。
Chrome拡張 PubMed2EndNote v3.0 の開発時に、Word COM自動操作による実験で確認した事実。本スキルの設計判断の根拠として記録する。
foreign-keys/db-id が無くてもEndNote（CWYW）はフィールドを引用として認識する（拡張機能は db-id なしで動作実証済み）。本スキルの ENDNOTE_DB_ID ハードコードは互換性のため維持しているが、必須ではない。w:rPr に w:highlight w:val="yellow" として付ける（本スキルの現行方式が正しい）。フィールドの「外側」に付けた書式は表示部分に継承されない — RTFの {\highlight7{\field...}} のような外側指定は、Wordに読み込ませると実はハイライトが付かないことを実験で確認した。ArticleIdList にDOIが無く Article/ELocationID[@EIdType='doi'] にのみ存在する。両対応が必要（実装済み）。ArticleDate[DateType=Electronic] が正式な電子出版日。History の entrez date はPubMed登録日であり、両者は異なることがある。電子出版日を優先する（実装済み）。docx の構造、ZIP編集手順、lxml使用時の落とし穴、段落削除時の注意、EndNoteフィールドの全仕様については以下を参照：
references/docx_xml_editing.md — docx ZIP解凍・XML編集・再圧縮ガイド（全10セクション）特に以下のトピックを扱う場合は必読：
endnote_inserter.py — メインスクリプト。PubMed XML 取得、パース、EndNote XML 生成、OOXML フィールドコード生成（形式A）、docx 内マーカー置換、XML バリデーションを一括実行。※ 過去のプロジェクトで使用した fix_flddata_umlauts.py（形式Bのウムラウト修正）や fix_refs_10_24.py（番号範囲の個別修正）は本ディレクトリには同梱していない。必要になったら本書の手順（形式Bのbase64エンコード仕様等）をもとに都度作成する。
連番引用 (3, 4) をビルド時に (3)(4) に分割した場合、同一 <w:t> 要素内に隣接するマーカーが含まれる。最初のマーカー (3) を置換するとXML構造が大きく変化し、同じマーカー番号の2回目の出現（例: 後方の単独 (3)）が find_run_boundaries で正しく認識されずスキップされることがある。
process_batch は全エントリ処理後に _scan_remaining_markers() で未変換マーカーを自動検出し、残存があれば最大3パスまで自動リトライする。PubMed APIデータはキャッシュされるため、リトライ時の追加API呼び出しは発生しない。
最終パス後もなお残存がある場合は WARNING を出力する。通常、2パス目で全マーカーが処理される。
process_batch の戻り値が True でも、WARNING が出力されていないかログを確認するprocess_batch のログに「✓ All markers successfully replaced (verified)」が出力されている基于 SOC 职业分类
