docx-processing-openai

DOCX スキル

使用するタイミング

• レイアウト（表、図、ページ区切り）が重要になる DOCX の内容を読み取りまたはレビューするとき。
• 専門的な書式を使って DOCX ファイルを作成または編集するとき。
• 納品前に視覚的なレイアウトを検証するとき。

ワークフロー

1. 可能であれば視覚的なレビュー（レイアウト、表、図）を優先します。
   • soffice と pdftoppm が利用可能な場合は、DOCX を PDF に変換し、さらに PNG に変換します。
   • または scripts/render_docx.py を使用します（pdf2image と Poppler が必要です）。
   • これらのツールが存在しない場合は、インストールするか、レンダリングされたページをローカルで確認するようユーザーに依頼します。
2. 編集や構造化された作成（見出し、スタイル、表、リスト）には python-docx を使用します。
3. 意味のある変更を加えるたびに再レンダリングし、ページを確認します。
4. 視覚的なレビューができない場合は、フォールバックとして python-docx でテキストを抽出し、レイアウト上のリスクを明記します。
5. 中間出力は整理された状態を保ち、最終承認後にクリーンアップします。

一時ファイルと出力の規則

• 中間ファイルには tmp/docs/ を使用し、作業終了後に削除します。
• このリポジトリで作業する場合、最終成果物は output/doc/ 配下に書き出します。
• ファイル名は安定していて、内容が分かるものにします。

依存関係（不足している場合はインストール）

依存関係の管理には uv を優先して使用します。

Python パッケージ:

uv pip install python-docx pdf2image

uv が利用できない場合:

python3 -m pip install python-docx pdf2image

システムツール（レンダリング用）:

# macOS (Homebrew)
brew install libreoffice poppler

# Ubuntu/Debian
sudo apt-get install -y libreoffice poppler-utils

この環境でインストールできない場合は、不足している依存関係と、ローカルでのインストール方法をユーザーに伝えます。

環境

必須の環境変数はありません。

レンダリングコマンド

DOCX -> PDF:

soffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX

PDF -> PNG:

pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME

同梱のヘルパー:

python3 scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages

品質の基準

• 納品先にそのまま提出できる文書を作成します。フォントの統一、行間・余白の一貫性、明確な階層構造を保ちます。
• 文字の切れやずれ、文字の重なり、崩れた表、読めない文字、初期テンプレートのままのスタイルといった書式上の欠陥を避けます。
• グラフ、表、ビジュアルは、正しい配置でレンダリングされたページ上で読みやすくなければなりません。
• ハイフンには ASCII のハイフン（-）のみを使用します。U+2011（ノーブレークハイフン）やその他の Unicode のダッシュは使用しないでください。
• 引用と参照は人が読める形式にし、ツールのトークンやプレースホルダー文字列を残してはいけません。

最終チェック

• 最終納品前に、すべてのページを 100% の拡大率で再レンダリングして確認します。
• 余白、配置、ページ区切りの問題を修正し、レンダリングの手順を繰り返します。
• ユーザーが保持を求めない限り、残存物（一時ファイル、重複したレンダリング結果）がないことを確認します。