docx-creator

DOCX Creator

minimax-skills:minimax-docx の上に構築された薄い拡張レイヤーです。ドキュメントエンジンではありません。

まずこれをお読みください。 OpenXML SDK の機能は minimax-docx にあります。このスキルにはエンジンコードは一切含まれていません。含まれているのは、エンジンの CLI がどこで使いものにならなくなるのか、中国語の正式文書で SDK を正しく使う方法、そして自分には問題なく見えても Word では崩れているファイルを納品しないための出力検証など、実際にデバッグに丸一日かかった知見です。

役割分担

レイヤー	担当	内容
OpenXML SDK（DocumentFormat.OpenXml）、WordprocessingDocument API、XSD バリデーター、スタイルテンプレート、OpenXML 百科事典	minimax-skills:minimax-docx	エンジンと参考ドキュメントです。ここでは重複させません。
CLI の表現力の限界と、C# に切り替えるタイミング	このスキル	ISSUE-001、ISSUE-002
中国語の正式文書向けに検証済みの Markdown から DOCX を生成するツール	このスキル	scripts/Program.cs
OpenXML で間違えやすい中国語の正式文書のタイポグラフィ規則	このスキル	以下の厳守ルールと ISSUE-004…007
実際のエンドツーエンドの視覚的検証手順	このスキル	references/verification_protocol.md

エンジンはマーケットプレイスのインストール先にあります。通常は ~/.claude/plugins/marketplaces/minimax-skills/skills/minimax-docx/ です。

このスキルで扱っていない構造的な機能（画像、変更履歴、コメント、目次、複数セクションのレイアウト、テンプレートの適用）については、minimax-docx のドキュメントを直接お読みください。SDK のパターンについては、その minimax-docx/references/ フォルダー（cjk_typography.md、openxml_element_order.md、 openxml_units.md、troubleshooting.md）と Samples/*.cs が信頼できる情報源です。ここで独自に作り直さないでください。

振り分け：このドキュメントにはどの方法を使いますか？

状況	方法
中国語の契約書／合意書／公文書／甲乙双方の情報ブロック、条項番号、署名欄、表を含む文書	scripts/Program.cs を使った C# OpenXML（このスキル）
太字／リスト／表がなく、通常の文章、見出し、段落だけの文書	minimax-docx CLI の create --content-json で十分です
既存の .docx に内容を入力または編集する	minimax-docx のパイプライン B（edit-content）と、このスキルのレイアウトおよび検証ガイダンス
既存の .docx の書式に合わせる	minimax-docx のパイプライン C（apply-template）
既存の Word/WPS 文書から、レイアウトを修復する／抜粋を選ぶ → PDF にする	Word の原本を保持し、references/word-to-pdf.md と references/verification_protocol.md に従ってください
Markdown → PDF	daymade-docs:pdf-creator

目安：CLI の --content-json が扱えるブロックタイプは heading、paragraph、pagebreak の3種類だけです。太字、リスト、表、罫線、フッター、フォント、配置は、いずれも指定できません。中国語の契約書では、これらすべてが必要です。ISSUE-001 を参照してください。

クイックスタート

ジェネレーターは Markdown を読み込み、書式設定済みの .docx を出力します。ビルド成果物がスキルのディレクトリに置かれないよう、ドキュメントの隣にコピーしてください。

# 1. Stage the generator beside your markdown
mkdir -p _docxgen && cp <skill-dir>/scripts/Program.cs <skill-dir>/scripts/mmdocx-gen.csproj \
   <skill-dir>/scripts/.gitignore _docxgen/

# 2. Generate (first run restores DocumentFormat.OpenXml + Markdig, ~20s)
dotnet run --project _docxgen -- your-doc.md your-doc.docx

# 3. Structural validation via the engine's XSD validator (note the roll-forward env — ISSUE-003)
DOTNET_ROLL_FORWARD=Major dotnet run \
  --project ~/.claude/plugins/marketplaces/minimax-skills/skills/minimax-docx/scripts/dotnet/MiniMaxAIDocx.Cli \
  -- validate --input your-doc.docx

# 4. MANDATORY visual verification — never skip, never substitute qlmanage
soffice --headless --convert-to pdf --outdir /tmp/docxcheck your-doc.docx
pdftoppm -png -r 100 /tmp/docxcheck/your-doc.pdf /tmp/docxcheck/page
# then Read every /tmp/docxcheck/page-NN.png

# 5. MANDATORY if Microsoft Word.app is installed — LibreOffice cannot see ISSUE-012
open -a "Microsoft Word" your-doc.docx   # check the title bar for "兼容性模式", check every page

コマンドの詳細とトラブルシューティングについては、scripts/README.md を参照してください。 検証手順と合否基準については、references/verification_protocol.md を参照してください。

厳守ルール（違反するとやり直しになります）

1. 配置は段落ごとに設定します — ここが最もコストのかかる部分です

文書全体の配置を一律に設定しないでください。内容に応じて、次の3種類の配置を使い分けます。

内容	配置	理由
文書タイトル（H1）	中央揃え	慣例
条項の見出し（H2+）	左揃え	慣例
情報ブロックと署名ブロック — 甲方/乙方/统一社会信用代码/法定代表人/日期など、つまり Markdown のソフト改行またはハード改行で行がつながっている段落	左揃え	両端揃えでは、段落の最終行を除くすべての行の間隔が広がります。複数行の情報ブロックは1つの段落なので、最終行以外のすべての行で文字間隔が大幅に広がります。
通常の本文	両端揃え（Both）	右端をきれいに揃えます

このルールは機械的に判定できるため、目視で判断しないでください。Markdown の段落のインラインツリーに LineBreakInline が含まれている場合はその段落を左揃えにし、含まれていない場合は両端揃えにします。Main のブロック振り分け switch にある case ParagraphBlock p: の分岐で実装されており、改行の検出は InlineRuns で行います。（行番号はファイルが大きくなるたびに変わるため、あえて記載していません。代わりに scripts/README.md の関数名検索表を参照してください。）詳しい説明は ISSUE-004 を参照してください。

2. 独立したリストは番号を最初から振り直し、継続リストは番号を引き継ぎます

Markdown の独立したリストごとに、それぞれ専用の NumId と、StartOverrideNumberingValue = 1 を持つ LevelOverride を設定してください。複数の条項で1つの NumId を使い回すと、第3条のリストが気づかないうちに4から始まります。case ListBlock lb: の分岐と NumberingDefinitionsPart の設定で実装されています。どちらも scripts/README.md の検索表を参照してください。この処理には、誤ったクラス名と誤った要素の順序という2つの SDK の落とし穴があります（ISSUE-005、ISSUE-006）。既存の Word リストでは、意図的な番号の継続を保持してください。書式を変更する前に numId とそのレベルを特定してください。numId=0 は番号付けを無効にします。テキストで入力された序数は文字列であり、自動リストではありません。ISSUE-016 を参照してください。

3. CJK フォントでは両方のフォント枠を設定する必要があります

ランには RunFonts { Ascii, HighAnsi, EastAsia } を設定してください。ラテン文字用の枠だけを設定すると、中国語の文字には Word の代替フォントが使われ、文書の表示は閲覧者のマシンの設定に左右されます。既定のフォントは、ラテン文字が Times New Roman、本文の東アジア文字が宋体、見出しが黑体です。中国語の太字ランではフォントファミリーを黑体に切り替えます。宋体には真の太字ウェイトがなく、レンダラーが太字を合成すると、画数の多い文字がぼやけます（ISSUE-014）。サイズの単位は OpenXML のハーフポイントです。本文は21（10.5pt。中国語の原稿で一般的なサイズ）、H1 は36（18pt）、条項の見出しは28（14pt）です。本文の段落には、1文字分の先頭行インデントも設定します（10.5pt で 420 twips。本文のサイズと合わせて変更してください）。ISSUE-007 を参照してください。

4. ページと表の基本設定

A4 のサイズは11906 × 16838 twips、余白は1440 twipsです。ページ番号は中央揃えのフッターに PAGE フィールドとして挿入します。表には6種類すべての罫線（top/bottom/left/right/insideH/insideV。順序は ECMA-376 に準拠します。ISSUE-013）と tblGrid（ISSUE-012）が必要です。罫線の一部を省略すると、印刷時にセルの枠線が表示されません。tblGrid を省略すると、LibreOffice では問題が見えなくても、ファイルは厳格な検証に失敗します。BuildTable と、Main の SectionProperties/FooterPart の設定で実装されています。scripts/README.md の検索表を参照してください。

検証は必須です

禁止：視覚的な証拠としての qlmanage のサムネイル。 macOS の Quick Look は Word とは異なるエンジンでレンダリングするため、情報ブロックの間隔が広がっている文書でも、見た目が問題のないページを平気で表示します。qlmanage の証拠をもとに文書を「完全に検証済み」と判断した結果、Word で開くと壊れていたことが、このルールの発端です。ISSUE-008。

必須の手順： 生成 → XSD 検証 → soffice --headless --convert-to pdf → pdftoppm -png → 各ページの画像をすべて Read → 5 つの失敗モードを確認 （情報ブロックが広がっていない／各リストが 1 から始まっている／表の罫線がある／署名ブロックが崩れていない／ページ分割で孤立した要素がない）→ Microsoft Word.app がインストールされている場合は、実際のファイルを開き、タイトルバーに「互換性モード」と表示されていることを確認して、すべてのページをチェックします。詳細、前提条件、「失敗と見なされるもの」の一覧については、references/verification_protocol.md を参照してください。

LibreOffice で問題なくレンダリングされることは、「Word でも正しくレンダリングされる」ことと同じではありません。 ISSUE-012 では、この手順に沿った LibreOffice ベースのすべてのチェックに合格したファイル（情報ブロックの間隔が適切で、番号が正しく、表も崩れていない）が、実際の Word で開くとタイトルバーに「互換性モード」と表示され、番号付けが一切設定されていない段落に、実体のない箇条書き記号が表示される事例が実際に再現されています。LibreOffice には同等のフォールバック経路がなく、この種の欠陥を検出することは構造上できません。寛容なレンダラーでは Word の動作が見落とされるという ISSUE-008 の教訓が、さらに一段上で繰り返されているのです。Word が利用可能で直接確認できる場合は、LibreOffice だけの検証を不完全なものとして扱ってください。

納品済みの .docx を上書きする前に、同じフォルダーに ~$<name>.docx がないか確認してください。これは Word の所有者ロックであり、受取人が古いバージョンを開いていることを意味します。上書き自体はできますが、受取人は文書を閉じて開き直すまで古い文書を見続けることになります。その旨を伝えてください。ISSUE-011。

カスタマイズ

scripts/Program.cs は約 260 行の分かりやすい OpenXML コードです。フォント、サイズ、間隔、罫線、新しいブロックタイプを変更する場合は、直接編集してください。それが想定されたワークフローです。構造に関わる機能（画像、目次、ヘッダー、変更履歴）を追加する前に、まず minimax-docx の該当する Samples/*.cs を読んでください。これらのパターンは SDK のバージョンで検証済みのため、コンパイルエラーの繰り返しを避けられます。

RunProperties、ParagraphProperties、TableProperties、TableCellProperties、または TableBorders に新しいプロパティを追加する場合は、C# で .Append() を自然に書ける位置ではなく、ECMA-376 で定められたその親要素の子要素の順序に従って配置してください。 これはスタイル上の好みではありません。順序を誤ると ISSUE-012／ISSUE-013 を再現することになります。つまり、minimax-docx validate は引き続き PASSED と報告し、LibreOffice ではファイルがきれいにレンダリングされる一方、実際の Word では互換モードで開き、要求していない書式が文書中に散在します。現在のコードには、各構築箇所（RunProps、Para、BuildTable）にスキーマ順序に関するコメントがすでにあります。末尾に追加するのではなく、既存のプロパティ一覧をその場で拡張してください。また、本当に新しい要素を追加する場合は、.Append() の位置を決める前に minimax-docx の openxml_element_order.md で位置を確認してください。このような変更の後は、検証プロトコルのステップ 3a（LibreOffice だけでなく、実際の Word）を再実行してください。この種のバグを検出できるのは、手順全体の中でこのチェックだけです。

参考資料

• references/word-to-pdf.md — 既存の Word 原稿、抜粋の選択、承認済みの変更履歴、レイアウトの修正、PDF の納品について説明します。Markdown への往復変換は行いません。
• references/known_issues.md — このパイプラインの構築中に遭遇したすべての落とし穴について、症状／根本原因／修正／検証をまとめています。問題をデバッグする前に読んでください。
• references/verification_protocol.md — エンドツーエンドの検証手順全体、前提条件、合格基準、禁止されている代替手段について説明します。
• scripts/README.md — ジェネレーターの実行方法、対応している Markdown、環境要件について説明します。