docx

DOCX の作成、編集、分析

🤖 エージェントと MCP の機能強化（Agent & MCP Enhancements）

この Skill は、最適な結果を得るために、特定のエージェントロールや MCP ツールとの併用をサポートし、推奨しています。

推奨エージェントロール

• Office Docx Architect：詳しくは AGENTS.md を参照してください。
  • このロールは、OOXML 構造の完全性と準拠性の修正に特化しています。
  • Trae でこのロールを設定すると、AI は単純なテキスト置換ではなく、より厳密な「解凍-編集-パッキング」の思考モードを自動的に採用します。

推奨 MCP ツール

• Filesystem MCP：AI が解凍後の XML ディレクトリを直接操作し、より詳細な構造検証を行えるようにします。
• Git MCP：ドキュメントの編集過程でバージョンをロールバックするために使用します。
• mcp-feedback-enhanced：AI がドキュメントの作成または編集中に、ask_followup_question を使って内容の詳細（「この段落の語調をもっとフォーマルにする必要がありますか？」など）や編集範囲（「すべての変更履歴を保持する必要がありますか？」など）をユーザーに確認できるようにします。

---

概要

ユーザーから、.docx ファイルの内容の作成、編集、分析を依頼される場合があります。.docx ファイルは基本的に、読み取りや編集が可能な XML ファイルやその他のリソースを含む ZIP アーカイブです。タスクに応じて、さまざまなツールやワークフローを利用できます。

ワークフローの判断ツリー

内容の読み取り／分析

以下の「テキスト抽出」または「生 XML へのアクセス」のセクションを使用してください。

新しいドキュメントの作成

「新しい Word ドキュメントの作成」ワークフローを使用してください。

既存のドキュメントの編集

• 自分のドキュメント＋簡単な変更 「基本的な OOXML 編集」ワークフローを使用してください。

• 他人のドキュメント 「変更履歴を記録するワークフロー」（デフォルトとして推奨）を使用してください。

• 法務、学術、ビジネス、または政府機関のドキュメント 「変更履歴を記録するワークフロー」（必須）を使用してください。

内容の読み取りと分析

テキスト抽出

ドキュメントのテキスト内容を読むだけでよい場合は、pandoc を使用してドキュメントを Markdown に変換してください。Pandoc はドキュメント構造の保持に優れており、変更履歴も表示できます。

# Convert document to markdown with tracked changes
pandoc --track-changes=all path-to-file.docx -o output.md
# Options: --track-changes=accept/reject/all

生 XML へのアクセス

コメント、複雑な書式設定、ドキュメント構造、埋め込みメディア、メタデータを扱うには、生 XML へのアクセスが必要です。これらの機能を利用するには、ドキュメントを展開し、生 XML の内容を読み取る必要があります。

ファイルの展開

python ooxml/scripts/unpack.py <office_file> <output_directory>

主要なファイル構造

• word/document.xml - ドキュメントの本文
• word/comments.xml - document.xml で参照されているコメント
• word/media/ - 埋め込み画像およびメディアファイル
• 変更履歴では <w:ins>（挿入）タグと <w:del>（削除）タグが使用されます。

新しい Word ドキュメントの作成

新しい Word ドキュメントを一から作成する場合は、JavaScript/TypeScript を使って Word ドキュメントを作成できる docx-js を使用してください。

ワークフロー

1. 必須 - ファイル全体を読む：docx-js.md（約 500 行）を最初から最後まで完全に読んでください。このファイルを読む際、範囲の制限を絶対に設定しないでください。ドキュメントの作成を始める前に、詳細な構文、重要な書式設定ルール、ベストプラクティスを確認するため、ファイル全体の内容を読んでください。
2. Document、Paragraph、TextRun コンポーネントを使用して JavaScript/TypeScript ファイルを作成します（すべての依存関係がインストール済みと想定できます。インストールされていない場合は、以下の依存関係のセクションを参照してください）。
3. Packer.toBuffer() を使用して .docx としてエクスポートします。

既存の Word ドキュメントの編集

既存の Word ドキュメントを編集する場合は、Document ライブラリ（OOXML 操作用の Python ライブラリ）を使用してください。このライブラリはインフラストラクチャのセットアップを自動的に処理し、ドキュメントを操作するメソッドを提供します。複雑なシナリオでは、ライブラリを通じて基盤となる DOM に直接アクセスできます。

ワークフロー

1. 必須 - ファイル全体を読む：ooxml.md（約 600 行）を最初から最後まで完全に読んでください。このファイルを読む際、範囲の制限を絶対に設定しないでください。ドキュメントファイルを直接編集するための Document ライブラリ API と XML パターンを確認するため、ファイル全体の内容を読んでください。
2. ドキュメントを展開します：python ooxml/scripts/unpack.py <office_file> <output_directory>
3. Document ライブラリを使用する Python スクリプトを作成して実行します（ooxml.md の「Document Library」セクションを参照）。
4. 最終ドキュメントをパッキングします：python ooxml/scripts/pack.py <input_directory> <office_file>

Document ライブラリは、一般的な操作向けの高レベルメソッドと、複雑なシナリオ向けの DOM への直接アクセスの両方を提供します。

文書レビューのための変更履歴ワークフロー

このワークフローでは、Markdown を使って包括的な変更履歴を計画してから、OOXML に反映できます。重要：変更履歴を完全に反映するには、すべての変更を体系的に実装する必要があります。

バッチ処理の方針：関連する変更を 3～10 件ずつのバッチにまとめます。これにより、効率を維持しながらデバッグを管理しやすくなります。次のバッチに進む前に、各バッチをテストしてください。

原則：最小限かつ正確な編集 変更履歴を実装するときは、実際に変更されるテキストだけに印を付けてください。変更されていないテキストを繰り返すと、編集内容のレビューが難しくなり、プロらしくない印象になります。置換は、[変更されないテキスト] + [削除] + [挿入] + [変更されないテキスト] に分割してください。変更されないテキストについては、元の <w:r> 要素を抽出して再利用し、元の run の RSID を保持してください。

例：「30 days」を文中で「60 days」に変更する場合：

# BAD - Replaces entire sentence
'<w:del><w:r><w:delText>The term is 30 days.</w:delText></w:r></w:del><w:ins><w:r><w:t>The term is 60 days.</w:t></w:r></w:ins>'

# GOOD - Only marks what changed, preserves original <w:r> for unchanged text
'<w:r w:rsidR="00AB12CD"><w:t>The term is </w:t></w:r><w:del><w:r><w:delText>30</w:delText></w:r></w:del><w:ins><w:r><w:t>60</w:t></w:r></w:ins><w:r w:rsidR="00AB12CD"><w:t> days.</w:t></w:r>'

変更履歴付き変更のワークフロー

1. Markdown 表現を取得する：変更履歴を保持したまま、ドキュメントを Markdown に変換します：

   pandoc --track-changes=all path-to-file.docx -o current.md
   

2. 変更を特定してグループ化する：ドキュメントを確認し、必要な変更をすべて特定して、論理的なバッチにまとめます：

   位置の特定方法（XML 内で変更箇所を探す）：

   • セクション／見出し番号（例：「Section 3.2」、「Article IV」）
   • 番号が付いている場合は段落識別子
   • 前後に固有のテキストを含む grep パターン
   • ドキュメントの構造（例：「最初の段落」、「署名欄」）
   • Markdown の行番号は使用しないでください。XML の構造とは対応していません。

   バッチの構成（関連する変更を1バッチあたり3～10件にまとめる）：

   • セクション別：「バッチ1：Section 2 の修正」、「バッチ2：Section 5 の更新」
   • 種類別：「バッチ1：日付の修正」、「バッチ2：当事者名の変更」
   • 複雑さ別：単純なテキスト置換から始め、その後、複雑な構造変更に取り組む
   • 順序別：「バッチ1：1～3ページ」、「バッチ2：4～6ページ」

3. ドキュメントを読み、展開する：

   • 必須 — ファイル全体を読む：ooxml.md（約600行）を最初から最後まで完全に読んでください。このファイルを読むときに範囲制限を指定してはいけません。「Document Library」と「Tracked Change Patterns」のセクションに特に注意してください。
   • ドキュメントを展開する：python ooxml/scripts/unpack.py <file.docx> <dir>
   • 推奨された RSID をメモする：unpack スクリプトは、変更履歴に使用する RSID を提案します。ステップ4bで使うために、この RSID をコピーしてください。

4. バッチごとに変更を実装する：セクション別、種類別、または近接箇所別に変更を論理的にまとめ、単一のスクリプトでまとめて実装します。この方法には次の利点があります：

   • デバッグが容易になります（バッチが小さいほど、エラーの特定が容易になります）
   • 段階的に作業を進められます
   • 効率を維持できます（1バッチあたり3～10件が適切です）

   推奨されるバッチのまとめ方：

   • ドキュメントのセクション別（例：「Section 3 の変更」、「定義」、「終了条項」）
   • 変更の種類別（例：「日付の変更」、「当事者名の更新」、「法律用語の置き換え」）
   • 近接箇所別（例：「1～3ページの変更」、「ドキュメントの前半部分の変更」）

   関連する変更の各バッチについて、次の手順を実行します：

   a. テキストを XML に対応付ける：word/document.xml でテキストを grep し、<w:r> 要素間でテキストがどのように分割されているかを確認します。

   b. スクリプトを作成して実行する：get_node を使ってノードを見つけ、変更を実装してから doc.save() を実行します。パターンについては、ooxml.md の 「Document Library」 セクションを参照してください。

   注：スクリプトを作成する直前に、必ず word/document.xml を grep して、現在の行番号を取得し、テキストの内容を確認してください。各スクリプトの実行後に行番号は変わります。

5. ドキュメントをパックする：すべてのバッチが完了したら、展開したディレクトリを .docx に戻します：

   python ooxml/scripts/pack.py unpacked reviewed-document.docx
   

6. 最終確認：ドキュメント全体を包括的に確認します：

   • 最終ドキュメントを Markdown に変換します：

     pandoc --track-changes=all reviewed-document.docx -o verification.md
     

   • すべての変更が正しく適用されたことを確認します：

     grep "original phrase" verification.md  # 見つからないこと
     grep "replacement phrase" verification.md  # 見つかること
     

   • 意図しない変更が加わっていないことを確認します

ドキュメントを画像に変換する

Word ドキュメントを視覚的に分析するには、次の2段階の手順で画像に変換します：

1. DOCX を PDF に変換する：

   soffice --headless --convert-to pdf document.docx
   

2. PDF の各ページを JPEG 画像に変換する：

   pdftoppm -jpeg -r 150 document.pdf page
   

   page-1.jpg、page-2.jpg などのファイルが作成されます。

オプション：

• -r 150：解像度を150 DPIに設定します（品質とサイズのバランスに合わせて調整してください）
• -jpeg：出力形式を JPEG にします（必要に応じて、PNG には -png を使用します）
• -f N：変換する最初のページを指定します（例：-f 2 は2ページ目から開始します）
• -l N：変換する最後のページを指定します（例：-l 5 は5ページ目で終了します）
• page：出力ファイルの接頭辞

特定の範囲を指定する例：

pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page  # Converts only pages 2-5

コードスタイルガイドライン

重要：DOCX 操作のコードを生成する際は、次の点に注意してください。

• 簡潔なコードを記述してください
• 冗長な変数名や重複した処理は避けてください
• 不要な print 文は避けてください

依存関係

必要な依存関係（利用できない場合はインストールしてください）：

• pandoc：sudo apt-get install pandoc（テキスト抽出用）
• docx：npm install -g docx（新しいドキュメントの作成用）
• LibreOffice：sudo apt-get install libreoffice（PDF 変換用）
• Poppler：sudo apt-get install poppler-utils（PDF を画像に変換する pdftoppm 用）
• defusedxml：pip install defusedxml（安全な XML 解析用）