docx

Docx スキル

小規模な CLI を使って、python-docx で Microsoft Word の .docx ファイルを作成、読み取り、編集、テンプレート化します。テキスト、スタイル、リスト、表、画像、ヘッダー／フッター、{{token}} のテンプレート処理、変更履歴（一覧表示／承認／却下）、コメント（一覧表示／追加／削除）、目次とページ番号フィールド、パッケージのヘルスチェックに対応しています。ドキュメント自体のレンダリングは行いません（PDF には LibreOffice が必要です。詳しくは「PDF への変換」を参照してください）。また、旧形式の .doc ファイルは編集できません。

使用する場面

• ユーザーから Word ドキュメント（レポート、手紙、契約書）の作成を依頼された場合。
• .docx のテキスト、アウトライン、スタイル、埋め込み画像が必要な場合。
• 既存の .docx を変更する必要がある場合：テキストの置換、表セルの編集、段落の挿入／削除、スタイルの適用、分割されたランの結合。
• データを使って入力する {{placeholders}} を含む .docx テンプレートがある場合。
• ドキュメントに確認、承認、または却下が必要な変更履歴がある場合。
• レビュアーのコメントを読んだり、コメントを追加／削除したりする必要がある場合。
• .docx が開けない、または動作がおかしく、破損状況の切り分けが必要な場合。
• ドキュメントに目次や「全 Y ページ中の X ページ」というフッターが必要な場合。
• 対象外：.doc（旧形式）、.odt、または WYSIWYG レイアウト作業。

前提条件

• python-docx がインストールされた Python 3.10 以降： pip install python-docx（インポート名は docx です。lxml も同梱されています）。
• コメントの add は、python-docx >= 1.2 ではネイティブ API を使用し、それ以前のバージョンでは XML にフォールバックします。どちらも自動で処理されます。
• 画像ブロックの場合：画像ファイルがローカルに存在している必要があります（PNG/JPEG）。

実行方法

すべてのヘルパーは、このファイルと同じ場所の scripts/ にあります。terminal ツールで実行してください。それぞれ --help に対応し、JSON を stdout に出力します。

python scripts/docx_create.py spec.json out.docx
python scripts/docx_read.py out.docx --text
python scripts/docx_edit.py replace out.docx --find old --replace new
python scripts/docx_template.py tpl.docx values.json filled.docx
python scripts/docx_revisions.py list out.docx
python scripts/docx_comments.py list out.docx
python scripts/docx_validate.py out.docx

クイックリファレンス

タスク	コマンド
JSON 仕様から作成	docx_create.py spec.json out.docx
全テキスト（本文＋表＋ヘッダー／フッター）	docx_read.py f.docx --text
見出しアウトライン＋表の形状	docx_read.py f.docx --structure
実際に使用されているスタイル	docx_read.py f.docx --styles
埋め込み画像を抽出	docx_read.py f.docx --images outdir/
変更履歴／コメントを検出	docx_read.py f.docx --revisions
検索／置換（書式を保持）	docx_edit.py replace f.docx --find A --replace B -o out.docx
表のセルを設定	docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X
インデックス N の前に段落を挿入	docx_edit.py insert f.docx --index N --text X --style Normal
段落 N を削除	docx_edit.py delete f.docx --index N
段落 N にスタイルを適用	docx_edit.py style f.docx --index N --style "Heading 1"
書式が同じ隣接ランを結合	docx_edit.py normalize f.docx -o out.docx
段落 N の前に目次フィールドを挿入	docx_edit.py toc f.docx --index N -o out.docx
「全 Y ページ中の X ページ」フッターフィールド	docx_edit.py page-numbers f.docx
{{tokens}} を入力	docx_template.py tpl.docx values.json out.docx --strict
変更履歴を一覧表示（ID／作成者／日付／テキスト）	docx_revisions.py list f.docx
すべての変更履歴を承認／却下	docx_revisions.py accept-all f.docx -o out.docx（または reject-all）
1 件の変更履歴を承認／却下	docx_revisions.py accept f.docx --id 3 -o out.docx
コメントを一覧表示（アンカー付きテキストを含む）	docx_comments.py list f.docx
テキストにアンカーされたコメントを追加	docx_comments.py add f.docx --target "phrase" --text "note" --author You
ID でコメントを削除	docx_comments.py delete f.docx --id 0
パッケージをヘルスチェック	docx_validate.py f.docx（エラー時は終了コード 1）

手順

1. 作成。 write_file で JSON 仕様を記述し、その後 scripts/docx_create.py を実行します。仕様では、page（サイズと余白を mm で指定）、header／footer の文字列、footer_page_numbers（ 「Page X of Y」フィールドをフッターに追加）、styles（フォント、サイズ、 太字／斜体、16 進数の color を指定するカスタム段落スタイル）、および blocks（heading（レベル 1～9）、paragraph（text または 各実行で bold／italic／underline を指定できる runs リスト）、 bullet_list、numbered_list、table（太字で表示される header 行、rows、Table Grid などの任意の組み込みテーブル style）、 image（path、任意の width_mm）、toc（目次フィールド）、 page_break）を指定できます。仕様の全形式は scripts/docx_create.py の先頭に記載されています。
2. 読み取り。 scripts/docx_read.py を、モードフラグを必ず 1 つだけ指定して 使用します。--text は本文の段落、すべてのテーブルセルのテキスト、 ヘッダー／フッターのテキストを JSON として返します。--structure は 見出しのアウトラインと、段落／テーブル／セクションの数を返します。 --images DIR は、word/media/ 以下のすべてのファイルをコピーします。
3. 編集。 scripts/docx_edit.py を使用します。replace は本文、テーブル （ネストされたものを含む）、ヘッダー、フッターを走査し、実行の書式を 保持します。ヘッダー／フッターを対象外にするには --body-only を追加します。 元のファイルを保持するには -o out.docx を指定し、省略すると上書き編集します。 insert／delete／style／toc の段落インデックスは、--structure／ --text における本文の順序を参照します。大幅な Word 編集を経た文書では、 先に normalize を実行してください。書式が同一の隣接する実行を結合し、 以降の検索置換が確実に一致するようにします。
4. 変更履歴を確認。 docx_revisions.py list は、本文、テーブル、 ヘッダー、フッターのすべてを対象に、各 w:ins と w:del（ID、作成者、 日付、影響を受けるテキスト）を報告します。accept-all／reject-all で 一括処理し、accept／reject --id N で個別の変更履歴を処理します。 承認すると挿入箇所は残り、削除されたテキストは削除されます。却下すると その逆になります。
5. コメント。 docx_comments.py list は、各コメントの ID、作成者、日付、 本文テキスト、およびコメントのアンカー先となっている文書テキストを返します。 add --target "some phrase" は、その語句の最初の出現箇所に新しいコメントを アンカーします（必要に応じて実行を分割し、書式を保持します）。 delete --id N は、文書テキストに触れずにコメントとマーカーを削除します。
6. テンプレート。 文書内に {{name}} 形式のトークンを配置します。 値を含む JSON オブジェクトを指定して scripts/docx_template.py を実行します。 トークンが未入力のまま残っている場合に失敗させるには --strict を使用します。 どちらの場合も、JSON 出力には filled の件数と unfilled_tokens が含まれます。
7. 検証（必ず実施）：--text または --structure で出力を再読み込みし、 変更履歴／コメントの操作で作成したものには docx_validate.py を実行します。

PDF への変換

スクリプトは不要です。LibreOffice がインストールされている場合は、ヘッドレスで変換します。

soffice --headless --convert-to pdf --outdir outdir/ file.docx

最初に利用可能か確認してください（command -v soffice || command -v libreoffice）。どちらもない場合は、この環境では PDF 変換を利用できないと ユーザーに伝えてください。代替手段を即興で用意しないでください。python-docx では PDF をレンダリングできず、レイアウトの忠実性には実際のレンダラーが必要です。

注意点

• トークンが複数のランに分割されます。 Word ではテキストが複数のランに分割されることがよくあります。置換ヘルパーは一致したランをまとめます（置換後のテキストには最初のランの書式が引き継がれます）。最初に docx_edit.py normalize を実行すると、以降のすべての編集で分割が減ります。
• 変更履歴の対応範囲。 docx_revisions.py は、ランレベルの挿入と削除（大多数を占めます）を解決します。段落記号や表の行に関する変更履歴、書式変更の記録、移動は --revisions で検出されますが、自動では解決されません。references/revisions-and-comments.md を参照し、これらは Word で処理してください。
• コメントのスレッド化。 返信と「解決済み」ステータスは commentsExtended.xml に保存されますが、このスキルでは無視されます。このスキルが追加するコメントは、スレッド化されていないトップレベルのコメントです。
• フィールドの結果は Word が計算します。 toc、page-numbers、および toc／footer_page_numbers の仕様オプションは、フィールドコードを書き込みます。実際の項目と番号は、ファイルを開いたときに Word／LibreOffice が設定します（Word ではフィールドの更新を求めるメッセージが表示される場合があります）。python-docx はこれらを計算しないため、その時点まではプレースホルダーテキストが表示されます。
• 検証は健全性チェックであり、スキーマ検証ではありません。 docx_validate.py は、zip、必須パーツ、リレーションシップのターゲット、画像のマジックバイト、参照されているスタイルを確認します。XSD 検証ではないため、検証を通過したファイルでも、Word が許容しない XML を含む場合があります。
• スタイル名は存在している必要があります。 ドキュメントで定義されていないスタイルを適用すると、KeyError が発生します。Heading 1、List Bullet、List Number、Table Grid などの組み込みスタイルはデフォルトのテンプレートに存在します。カスタムスタイルは、先に作成仕様で宣言する必要があります。
• 番号付きリストは番号がリセットされません。 List Number は Word のデフォルトの番号付けに依存するため、同じドキュメント内の別々のリストで番号がリセットされず、続きになる場合があります。複数のリストで厳密な番号付けが必要なユーザーには、その旨を伝えてください。
• セルへの書き込みで書式が置き換えられます。 set-cell は cell.text = ... を使用するため、そのセルのランはプレーンな書式にリセットされます。
• エンコーディング。 すべての JSON 仕様ファイル／値ファイルは UTF-8 として明示的に読み込まれます。独自のグルーコードを書く際に、ロケールのデフォルトに頼らないでください。
• XML を解凍して sed で編集しないでください。 編集にはスクリプト（または python-docx）を使用してください。document.xml のテキストを直接置換すると、ファイルが簡単に破損します。patch／write_file は JSON 入力にのみ使用し、.docx 自体には使用しないでください。

検証

• 作成、編集、テンプレート処理の後に docx_read.py out.docx --text を実行し、期待する文字列が表示され、古い文字列が消えていることを確認します。
• 変更履歴を承認または却下した後は、docx_revisions.py list が []（または意図的に残した ID のみ）を返すことを確認します。コメントを編集した後は、docx_comments.py list に変更が反映されていること、および --text の出力が変わっていないことを確認します。
• 正常なパッケージでは、docx_validate.py out.docx は "ok": true とともに終了コード 0 を返します。変更履歴、コメント、フィールドを操作した後は必ず実行してください。
• テンプレートには --strict を付けて実行するか、unfilled_tokens == [] であることを確認します。
• 構造の確認：--structure で期待する見出し構成と表の形状が表示されることを確認します。--styles でカスタムスタイルが適用されたことを確認できます。