docx

Word ドキュメント

Word の機能についてはすでにご存じでしょう。このスキルでは、コードからは見えない部分を補います。変更履歴やコメントを正しく扱うライブラリ、未追跡の編集を検出する検証機能、読者の視点でページを確認する方法、そしてファイルの破損をひそかに招く docx-js と OOXML の挙動について説明します。

スクリプトの実行

<skill> はこのファイルがあるディレクトリです。バンドルされているスクリプトは、ユーザーの作業ディレクトリから絶対パスで実行してください。そうすれば、スクリプト内の相対パスが正しく機能します。

uv run <skill>/ooxml/scripts/unpack.py contract.docx unpacked

作成した Python は、依存関係を宣言して実行してください。uv run --with defusedxml script.py を使うか、PEP 723 ヘッダーを付けてください。Node スクリプトは NODE_PATH=<skill>/node_modules node build.js として実行してください。<skill>/node_modules がない場合は、<skill> 内で一度 npm install を実行してください。ページのレンダリングには LibreOffice（soffice）と poppler（pdftoppm）が必要です。読み取りには pandoc が必要です。

ワークフローの選択

タスク	使用方法
テキストを読む	pandoc --track-changes=all file.docx -t markdown。変更履歴とコメントも表示されます。どちらか一方の状態を確認するには、all の代わりに accept または reject を指定します。
ドキュメントを作成する	docx-js：まず docx-js.md を読んでください。ファイルの破損につながるページサイズ、スタイル、画像の挙動について説明しています。
他の人のドキュメント、または法務、学術、ビジネス、公式文書を編集する	すべての編集を確認できるよう、変更履歴を使用します。以下の変更履歴ワークフローに従ってください。
このセッションで作成したドキュメントを少しだけ編集する	同じライブラリを使い、変更履歴は付けません。編集後、doc.save(require_tracking=False) を呼び出します。これでもスキーマの検証は行われます。大幅な変更の場合は、docx-js でファイルを再生成してください。
コメント、メタデータ、埋め込みメディア、未加工の構造	XML を展開して読みます。パターンについては ooxml.md を参照してください。

変更履歴ワークフロー

1. 読み取ります。 上記の pandoc でドキュメントを変換し、行う変更をすべてリストアップします。各箇所は前後のテキストを使って特定してください。Markdown の行番号は XML と関係がないため、使わないでください。
2. 展開します。 uv run <skill>/ooxml/scripts/unpack.py contract.docx unpacked を実行すると、推奨される RSID が表示されます。これを Document(..., rsid=...) に渡すと、このセッションの編集に同じリビジョン ID が使われます。
3. 編集します。 ooxml.md を読んでから、Document ライブラリを使うスクリプトを作成します。tracked_replace(old, new) は多くの編集に対応しており、複数のランにまたがるテキストを探して、異なる単語だけに変更履歴を付けます。関連する変更を数件から十数件ずつ、まとめて処理してください。失敗した箇所を特定しやすくなります。各バッチの前に unpacked/word/document.xml を再度 grep してください。保存のたびに行番号が変わるためです。
4. 保存します。 doc.save() は、未追跡の編集が含まれている場合、またはスキーマに違反する XML が含まれている場合、ドキュメントの書き込みを拒否し、差分を表示します。検証を省略するのではなく、スクリプトを修正してください。
5. 再パッケージ化します。 uv run <skill>/ooxml/scripts/pack.py unpacked reviewed.docx を実行してファイルを再パッケージ化し、LibreOffice で開けることを確認します。
6. 検証します。 pandoc --track-changes=all reviewed.docx -t markdown を実行し、意図した変更がすべて反映され、他には変更がないことを確認します。その後、以下の手順で出力を確認してください。

既存の変更を承認または却下するには、自分で編集を行う前に doc.accept_all_changes() または doc.reject_all_changes() を呼び出してください。

出力の確認

1. 検証します。 uv run <skill>/ooxml/scripts/validate.py reviewed.docx --original contract.docx は、スキーマと、元のドキュメントからのすべての変更に変更履歴が付いていることを確認します。doc.save() でも同じ検証が行われます。その作成者による以前の挿入箇所を直接編集できるようにするには、--author NAME を渡してください。新規に作成したドキュメントの場合は、--original を省略するとスキーマのみを検証します。
2. 目視確認します。 uv run <skill>/ooxml/scripts/render.py reviewed.docx pages を実行すると、ページごとに PNG のパスが表示されます（範囲を指定する場合は --pages 2-4）。作成または再構成したドキュメントを納品する前に、ページを確認してください。LibreOffice では docx-js の目次が空のままレンダリングされます。ファイルを開くと Word が目次を埋め込みます。

気づかないうちに失敗する落とし穴

• 他の著者による変更の一部を編集すること。 他の人が追加したテキストを削除するには、その中に自分の <w:del> を入れてください。相手のテキストを直接編集してはいけません。
• pandoc をエディターとして使うこと。 文書全体を書き換え、書式、コメント、変更履歴を削除します。読み取りにのみ使用し、成果物の作成には使用しないでください。