docx

DOCX の作成、編集、分析

概要

.docx ファイルは、XML ファイルを含む ZIP アーカイブです。

クイックリファレンス

タスク	方法
内容を読み取る／分析する	pandoc を使うか、展開して生の XML を確認します
新しいドキュメントを作成する	docx-js を使用します — references/docx-js.md を参照してください
既存のドキュメントを編集する	展開 → XML を編集 → 再パッケージ化します
変更履歴（変更履歴の記録）	Document ライブラリを使用します — references/ooxml.md を参照してください

.doc を .docx に変換する

編集する前に、従来形式の .doc ファイルを変換する必要があります。

python scripts/soffice.py --headless --convert-to docx document.doc

内容を読み取る

# Text extraction with tracked changes
pandoc --track-changes=all document.docx -o output.md

# Raw XML access
python scripts/unpack.py document.docx unpacked/

画像に変換する

python scripts/soffice.py --headless --convert-to pdf document.docx
pdftoppm -jpeg -r 150 document.pdf page

変更履歴を承諾する

すべての変更履歴を承諾したクリーンなドキュメントを生成するには、次の手順を実行します（LibreOffice が必要です）。

python scripts/accept_changes.py input.docx output.docx

---

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

JavaScript を使って .docx ファイルを生成します。完全な API リファレンスについては、references/docx-js.md を参照してください。

ワークフロー

1. 必須 — ファイル全体を読む：作業を進める前に、references/docx-js.md を最後まで読んでください。
2. Document、Paragraph、TextRun コンポーネントを使って、JavaScript／TypeScript ファイルを作成します。
3. 検証します：python scripts/validate.py --original <any_existing.docx> unpacked/ またはパッケージ化した後に実行します。

---

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

以下の 3 つの手順を順番どおりに実行してください。

手順 1：展開する

python scripts/unpack.py document.docx unpacked/

XML を抽出し、整形して出力し、隣接する run を結合し、変更履歴を簡略化し、スマート引用符を XML エンティティ（“ など）に変換して、編集後も保持されるようにします。run の結合を省略するには、--merge-runs false を使用してください。

展開スクリプトが出力する推奨 RSID に注意してください — 変更履歴にはこの値を使用します。

手順 2：XML を編集する

unpacked/word/ 内のファイルを編集します。XML のパターンと Document ライブラリ API については、references/ooxml.md を参照してください。

方法は 2 つあります。

1. XML を直接編集する — 文字列の置換には、エージェントの標準編集ツールを使用します。単純な変更履歴や、手順が明確な編集に適しています。
2. Document ライブラリ（Python） — 複雑な一括操作、プログラムによるノード検索、変更履歴のワークフローに使用します。references/ooxml.md の「Document Library」セクションを参照してください。

Document ライブラリの使用

# Set PYTHONPATH to the skill root, then run your script
PYTHONPATH=/path/to/docx-skill uv run your_script.py

from scripts.document import Document, DocxXMLEditor

doc = Document("unpacked", author="Claude", initials="C")
node = doc["word/document.xml"].get_node(tag="w:r", contains="old text")
doc["word/document.xml"].replace_node(node, "<w:del>...<w:ins>...")
doc.save()

コメントの追加

複数の XML ファイルにまたがる定型処理には、comment.py を使用します。

python scripts/comment.py unpacked/ 0 "Comment text with & and ’"
python scripts/comment.py unpacked/ 1 "Reply text" --parent 0  # reply to comment 0

次に、document.xml にマーカーを追加します（references/ooxml.md の「Comments」を参照してください）。

手順 3：パッケージ化する

python scripts/pack.py unpacked/ output.docx --original document.docx

自動修復による検証を行い、XML を圧縮して DOCX を作成します。検証を省略するには、--validate false を使用してください。

自動修復で修正されるもの：

• durableId が 0x7FFFFFFF 以上の場合（有効な ID を再生成します）
• 空白を含む <w:t> に xml:space="preserve" がない場合

自動修復で修正されないもの：

• 不正な XML、無効な要素の入れ子、リレーションシップの欠落、スキーマ違反

---

ドキュメントレビューの変更履歴ワークフロー

このワークフローは、他の人のドキュメントに包括的な変更履歴を記録するためのものです。Document ライブラリ API と XML パターンの詳細については、references/ooxml.md を参照してください。

一括処理の方針：関連する変更を 3～10 件ずつのグループにまとめます。これにより、効率を保ちながらデバッグを管理しやすくなります。

原則：最小限かつ正確に編集する 実際に変更されるテキストだけに印を付けます。変更されていないテキストを繰り返すと、レビューが難しくなり、プロらしくない印象を与えます。置換は、［変更されないテキスト］＋［削除］＋［挿入］＋［変更されないテキスト］に分割します。

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

1. Markdown 形式を取得する：pandoc --track-changes=all path-to-file.docx -o current.md
2. 変更を特定してグループ化する：論理的なバッチ（セクション、種類、または近接性別）に整理します
3. ドキュメントを読み、展開する：
   • 必須：references/ooxml.md を最後まで読みます
   • 展開します：python scripts/unpack.py file.docx dir
   • 提案された RSID をメモします
4. バッチごとに変更を実装する：複雑な操作には Document Library を使用し、単純な操作には XML を直接編集します
5. パックする：python scripts/pack.py dir reviewed.docx --original file.docx
6. 最終確認：pandoc --track-changes=all reviewed.docx -o verification.md

---

依存関係

• pandoc：テキストの抽出（apt-get install pandoc）
• docx：新しいドキュメント用（npm install -g docx）
• LibreOffice：PDF 変換、変更履歴の承認（scripts/soffice.py 経由）
• Poppler：画像用の pdftoppm（apt-get install poppler-utils）
• defusedxml：安全な XML 解析（pip install defusedxml）