Docx スキル
Microsoft Word の .docx ファイルを作成、読み取り、編集、テンプレート処理するためのスキルです。
python-docx を利用した小さなCLIツール群で動作します。テキスト、スタイル、リスト、表、画像、ヘッダー/フッター、{{token}} テンプレート、変更履歴（一覧表示/承認/却下）、コメント（一覧表示/追加/削除）、目次（TOC）とページ番号フィールド、そしてパッケージのヘルスチェックを処理できます。
文書自体のレンダリングは行いません（PDF 変換には LibreOffice が必要です — 「PDF への変換」を参照）、またレガシーな .doc ファイルの編集はサポートしていません。
使用する場合
- ユーザーが Word 文書（レポート、手紙、契約書など）の生成を依頼した場合。
.docxファイルのテキスト、アウトライン、スタイル、埋め込み画像を取得する必要がある場合。- 既存の
.docxファイルを変更する必要がある場合：テキストの置換、表セルの編集、段落の挿入/削除、スタイルの適用、断片化されたランの結合など。 {{placeholders}}を含む.docxテンプレートをデータで埋める必要がある場合。- 文書に変更履歴が含まれており、それをレビュー、承認、または却下する必要がある場合。
- レビューアのコメントを読んだり、コメントを追加/削除する必要がある場合。
.docxファイルが開かない、または正常に動作しない場合に破損の診断を行う必要がある場合。- 文書に目次や「X / Y ページ」フッターが必要な場合。
- 対象外：
.doc（レガシー）、.odt、または WYSIWYG レイアウト作業。
前提条件
- Python 3.10 以上、および
python-docxがインストールされていること：pip install python-docx（インポート名はdocxです。lxml は同梱されています）。 - コメントの
add機能は、python-docx 1.2 以上ではネイティブAPIを、それ以前のバージョンでは XML フォールバックを使用します — どちらも自動的に処理されます。 - 画像ブロックを使用する場合：画像ファイル（PNG/JPEG）がローカルに存在している必要があります。
実行方法
すべてのヘルパースクリプトはこのファイルと同じディレクトリの scripts/ にあります。terminal ツールを使って実行します。各スクリプトは --help をサポートし、JSON を標準出力に出力します。
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 の前に TOC フィールドを挿入 | docx_edit.py toc f.docx --index N -o out.docx |
| 「X / Y ページ」フッターフィールド | 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（エラー時は exit 1） |
手順
- 作成。 JSON 仕様ファイルを
write_fileで作成し、scripts/docx_create.pyを実行します。仕様は以下をサポートします：page（サイズ + ミリ単位の余白）、header/footer文字列、footer_page_numbers（「X / Y ページ」フッターフィールドを追加）、styles（フォント、サイズ、太字/斜体、16進数colorを指定可能なカスタム段落スタイル）、そしてblocks—heading（レベル 1-9）、paragraph（textまたは各ランがbold/italic/underlineを設定可能なrunsリスト）、bullet_list、numbered_list、table（header行は太字で表示、rows、オプションの組み込みテーブルstyle（例：Table Grid））、image（path、オプションのwidth_mm）、toc（目次フィールド）、page_break。完全な仕様形式はscripts/docx_create.pyの先頭に文書化されています。 - 読み取り。
scripts/docx_read.pyを、正確に1つのモードフラグを指定して使用します。--textは本文段落、すべての表セルのテキスト、ヘッダー/フッターテキストを JSON として返します。--structureは見出しアウトラインと段落/表/セクションの数を返します。--images DIRはパッケージ内のword/media/以下のすべてのファイルを指定ディレクトリにコピーします。 - 編集。
scripts/docx_edit.pyを使用します。replaceは本文、表（入れ子含む）、ヘッダー、フッターを走査し、ラン書式を保持します。--body-onlyを追加するとヘッダー/フッターをスキップします。-o out.docxを指定すると元のファイルを保持し、省略するとその場で編集します。insert/delete/style/tocの段落インデックスは、--structure/--textの本文順序を参照します。最初にnormalizeを実行すると、Word での激しい編集を経た文書の隣接する同一書式のランを結合し、後の検索/置換が確実に一致するようになります。 - 変更履歴のレビュー。
docx_revisions.py listは、本文、表、ヘッダー、フッター内のすべてのw:insとw:del（ID、作者、日付、影響を受けるテキスト）を報告します。accept-all/reject-allで一括解決、accept/reject --id Nで単一の変更を処理します。承認は挿入を保持し削除テキストを削除、却下はその逆を行います。 - コメント。
docx_comments.py listは各コメントの ID、作者、日付、本文テキスト、およびそれがアンカーされている文書テキストを返します。add --target "some phrase"は、指定されたフレーズの最初の出現箇所に新しいコメントをアンカーします（必要に応じてランが分割され、書式は保持されます）。delete --id Nは文書テキストに触れることなくコメントとそのマーカーを削除します。 - テンプレート。 文書内に
{{name}}形式のトークンを配置します。scripts/docx_template.pyを、値の JSON オブジェクトと共に実行します。--strictを使用すると、未埋めのトークンが残っている場合にエラーで終了します。JSON 出力は、いずれの場合もfilledカウントとunfilled_tokensをリストします。 - 検証（常に実行）：出力を
--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 のデフォルトの番号付けに依存します。1つの文書内の別々のリストは、番号をリセットせずに継続する場合があります。正確な複数リストの番号付けが必要なユーザーには警告してください。 - セル書き込みは書式を置き換える。
set-cellはcell.text = ...を使用するため、そのセルのランはプレーンな書式にリセットされます。 - エンコーディング。 すべての JSON 仕様/値ファイルは明示的に UTF-8 として読み取られます。独自のグルーコードを書く場合は、ロケールのデフォルトに決して依存しないでください。
- XML を unzip して 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は正常なパッケージの場合、exit 0 で"ok": trueを返します — 変更履歴/コメント/フィールド操作の後は必ず実行してください。- テンプレートは
--strictで実行するか、unfilled_tokens == []を確認します。 - 構造チェック：
--structureは期待される見出しアウトラインと表の形状を表示し、--stylesはカスタムスタイルが適用されたことを確認します。