Docx

DOCX の作成、編集、分析

🎯 PAI のコンテキスト全体を読み込む

このスキルを使って作業を始める前に、PAI のコンテキスト全体を読み込んでください：

read ~/.claude/PAI/SKILL.md

これにより、次の情報にアクセスできます：

• 連絡先リスト全体（Angela、Bunny、Saša、Greg、チームメンバー）
• 技術スタックの優先事項（TypeScript>Python、bun>npm、uv>pip）
• セキュリティルールとリポジトリの安全性に関する手順
• 応答形式の要件（絵文字を使った構造化形式）
• エージェントのルーティング用の音声 ID（ElevenLabs）
• 個人の好みと操作手順

このスキルを有効にするタイミング

Word 文書の作成

• ユーザーが「Word 文書を作成」「新しい docx」「文書を作成」と言った場合
• ユーザーが一からプロフェッショナルな文書を生成したい場合
• 表、画像、複雑なレイアウトを含む書式付き文書が必要な場合

Word 文書の編集

• ユーザーが「Word 文書を編集」「docx を変更」「文書を更新」と言った場合
• 「変更履歴」「赤入れ」「文書レビュー」に言及した場合
• 既存の .docx ファイルの内容を追加、削除、変更したい場合
• コメント、書式、文書構造を扱う必要がある場合

文書の読み取りと分析

• ユーザーが「docx を読む」「Word からテキストを抽出」「文書を分析」と言った場合
• 変更履歴、コメント、文書のメタデータを確認したい場合
• 文書を他の形式（Markdown、PDF、画像）に変換する必要がある場合
• 文書の構造や生の OOXML を調べたい場合

コンテキストに応じた有効化

• ユーザーが .docx ファイルまたは Word 文書へのパスを提示した場合
• プロフェッショナル、法律、学術、ビジネス関連の文書を扱っている場合
• 書式や変更履歴を保持したり、文書の完全性を維持したりする必要がある場合

概要

ユーザーから .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 library（OOXML を操作するための Python ライブラリ）を使用してください。このライブラリはインフラストラクチャのセットアップを自動で処理し、文書を操作するためのメソッドを提供します。複雑なシナリオでは、ライブラリを通じて基盤となる DOM に直接アクセスできます。

ワークフロー

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

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

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

このワークフローでは、OOXML に実装する前に Markdown を使って、包括的な変更履歴を計画できます。重要：変更履歴を漏れなく作成するには、すべての変更を体系的に実装する必要があります。

バッチ処理の方針：関連する変更を 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件まとめます）：

   • セクション別：「Batch 1: Section 2 amendments」、「Batch 2: Section 5 updates」
   • 種類別：「Batch 1: Date corrections」、「Batch 2: Party name changes」
   • 複雑さ別：まず簡単なテキスト置換から始め、次に複雑な構造変更に取り組みます
   • 順番別：「Batch 1: Pages 1-3」、「Batch 2: Pages 4-6」

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

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

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

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

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

   • ドキュメントのセクション別（例：「Section 3 changes」、「Definitions」、「Termination clause」）
   • 変更の種類別（例：「Date changes」、「Party name updates」、「Legal term replacements」）
   • 変更箇所の近接性別（例：「Changes on pages 1-3」、「Changes in first half of document」）

   関連する変更をまとめた各バッチで、次の作業を行います：

   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 文を避ける

例

例 1：ゼロからドキュメントを作成する

User: "Create a Word doc with my consulting proposal"
→ Reads docx-js.md for syntax
→ Builds document with headers, body text, tables
→ Exports .docx file to specified location

例 2：契約書をレビューして修正履歴を付ける

User: "Add tracked changes to this contract - change the payment terms"
→ Unpacks document, reads ooxml.md
→ Implements tracked changes with proper <w:ins>/<w:del> tags
→ Repacks document with visible redlines for review

例 3：Word ファイルからコンテンツを抽出する

User: "What's in this Word doc?"
→ Converts to markdown using pandoc
→ Preserves tracked changes and structure
→ Returns readable text with formatting preserved

依存関係

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

• 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 解析用）