minimax-docx

minimax-docx

OpenXML SDK（.NET）を基盤として、CLI ツールまたは C# スクリプトを直接使い、DOCX 文書を作成、編集、書式設定します。

セットアップ

初回のみ： bash scripts/setup.sh（Windows では powershell scripts/setup.ps1。省略可能な依存関係をスキップするには --minimal を指定します）。

セッション中の最初の操作： scripts/env_check.sh を実行します。NOT READY の場合は先に進まないでください。（同じセッション内の以降の操作ではスキップします。）

クイックスタート：C# を直接使う方法

カスタムスタイル、複雑な表、複数セクションのレイアウト、ヘッダー／フッター、目次、画像など、文書構造の操作が必要なタスクでは、CLI の制約に苦労するより、C# を直接記述してください。次のひな形を使います。

// File: scripts/dotnet/task.csx  (or a new .cs in a Console project)
// dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script task.csx
#r "nuget: DocumentFormat.OpenXml, 3.2.0"

using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;

using var doc = WordprocessingDocument.Create("output.docx", WordprocessingDocumentType.Document);
var mainPart = doc.AddMainDocumentPart();
mainPart.Document = new Document(new Body());

// --- Your logic here ---
// Read the relevant Samples/*.cs file FIRST for tested patterns.
// See Samples/ table in References section below.

C# を記述する前に、関連する Samples/*.cs ファイルを必ず読んでください。 コンパイル可能で、SDK バージョンに基づいて検証済みのパターンが記載されています。以下の「参考資料」セクションにある Samples の表で、トピックに対応するファイルを確認できます。

CLI の省略表記

以下のすべての CLI コマンドでは、$CLI を次の省略表記として使用します。

dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli --

パイプラインの振り分け

ユーザーが入力用の .docx ファイルを用意しているかどうかを確認して、振り分けます。

User task
├─ No input file → Pipeline A: CREATE
│   signals: "write", "create", "draft", "generate", "new", "make a report/proposal/memo"
│   → Read references/scenario_a_create.md
│
└─ Has input .docx
    ├─ Replace/fill/modify content → Pipeline B: FILL-EDIT
    │   signals: "fill in", "replace", "update", "change text", "add section", "edit"
    │   → Read references/scenario_b_edit_content.md
    │
    └─ Reformat/apply style/template → Pipeline C: FORMAT-APPLY
        signals: "reformat", "apply template", "restyle", "match this format", "套模板", "排版"
        ├─ Template is pure style (no content) → C-1: OVERLAY (apply styles to source)
        └─ Template has structure (cover/TOC/example sections) → C-2: BASE-REPLACE
            (use template as base, replace example content with user content)
        → Read references/scenario_c_apply_template.md

複数のパイプラインにまたがる依頼の場合は、順番に実行します（例：Create の後に Format-Apply）。

前処理

必要に応じて .doc → .docx に変換します：scripts/doc_to_docx.sh input.doc output_dir/

編集前にプレビューします（生の XML を読み込まずに済みます）：scripts/docx_preview.sh document.docx

編集時には構造を分析します：$CLI analyze --input document.docx

シナリオ A：作成

まず references/scenario_a_create.md、references/typography_guide.md、references/design_principles.md を読みます。文書の種類に合ったデザインレシピを Samples/AestheticRecipeSamples.cs から選び、書式の値を独自に考案しないでください。CJK の場合は、references/cjk_typography.md も読みます。

方法を選択します：

• シンプル（プレーンテキスト、最小限の書式設定）：CLI を使用します — $CLI create --type report --output out.docx --config content.json
• 構造的（カスタムスタイル、複数セクション、目次、画像、複雑な表）：C# を直接記述します。まず関連する Samples/*.cs を読みます。

CLI オプション：--type（report|letter|memo|academic）、--title、--author、--page-size（letter|a4|legal|a3）、--margins（standard|narrow|wide）、--header、--footer、--page-numbers、--toc、--content-json。

その後、検証パイプライン（以下）を実行します。

シナリオ B：編集／入力

まず references/scenario_b_edit_content.md を読みます。プレビュー → 分析 → 編集 → 検証の順に進めます。

方法を選択します：

• シンプル（テキストの置換、プレースホルダーへの入力）：CLI のサブコマンドを使用します。
• 構造的（セクションの追加／再編成、スタイルの変更、表の操作、画像の挿入）：C# を直接記述します。references/openxml_element_order.md と関連する Samples/*.cs を読みます。

使用可能な CLI 編集サブコマンド：

• replace-text --find "X" --replace "Y"
• fill-placeholders --data '{"key":"value"}'
• fill-table --data table.json
• insert-section、remove-section、update-header-footer

$CLI edit replace-text --input in.docx --output out.docx --find "OLD" --replace "NEW"
$CLI edit fill-placeholders --input in.docx --output out.docx --data '{"name":"John"}'

その後、検証パイプラインを実行します。また、変更を最小限に抑えられたことを確認するため、差分も実行します：

$CLI diff --before in.docx --after out.docx

シナリオ C：テンプレートの適用

まず references/scenario_c_apply_template.md を読みます。元の文書とテンプレートの両方をプレビューして分析します。

$CLI apply-template --input source.docx --template template.docx --output out.docx

複雑なテンプレート操作（複数テンプレートの結合、セクションごとのヘッダー／フッター、スタイルの結合）では、C# を直接記述します。必要なパターンについては、以下の「重要なルール」を参照してください。

検証パイプラインを実行し、その後ゲートチェックを実行します：

$CLI validate --input out.docx --gate-check assets/xsd/business-rules.xsd

ゲートチェックは必須要件です。合格するまで納品しないでください。不合格の場合は、原因を特定して修正し、再実行します。

また、コンテンツが保持されていることを確認するため、差分を確認します：$CLI diff --before source.docx --after out.docx

検証パイプライン

書き込み操作のたびに実行します。シナリオ C ではパイプライン全体の実行が必須です。シナリオ A／B では推奨です（操作が非常に単純な場合に限り省略できます）。

$CLI merge-runs --input doc.docx                                    # 1. consolidate runs
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd     # 2. XSD structure
$CLI validate --input doc.docx --business                           # 3. business rules

XSD 検証に失敗した場合は、自動修復して再試行します：

$CLI fix-order --input doc.docx
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd

それでも XSD 検証に失敗する場合は、ビジネスルールとプレビューによる確認に切り替えます：

$CLI validate --input doc.docx --business
scripts/docx_preview.sh doc.docx
# Verify: font contamination=0, table count correct, drawing count correct, sectPr count correct

最終プレビュー：scripts/docx_preview.sh doc.docx

重要なルール

ファイルの破損を防ぐためのルールです。OpenXML では要素の順序が厳密に定められています。

要素の順序（プロパティは常に先頭）：

親要素	順序
w:p	pPr → runs
w:r	rPr → t/br/tab
w:tbl	tblPr → tblGrid → tr
w:tr	trPr → tc
w:tc	tcPr → p（最小 1 個の <w:p/>）
w:body	ブロックコンテンツ → sectPr（最後の子要素）

直接書式の混入： ソース文書からコンテンツをコピーすると、インラインの rPr（フォント、色）と pPr（罫線、網かけ、間隔）がテンプレートのスタイルを上書きします。直接書式は必ず削除し、pStyle の参照と t のテキストだけを残してください。表も（セル内の pPr/rPr を含めて）クリーンアップしてください。

変更履歴： <w:del> では <w:delText> を使用し、<w:t> は使用しません。<w:ins> では <w:t> を使用し、<w:delText> は使用しません。

フォントサイズ： w:sz = ポイント数 × 2（12pt → sz="24"）。余白／間隔の単位は DXA です（1 inch = 1440、1cm ≈ 567）。

見出しスタイルには OutlineLevel が必須です： 見出しスタイル（Heading1、ThesisH1 など）を定義するときは、StyleParagraphProperties に必ず new OutlineLevel { Val = N } を含めてください（H1→0、H2→1、H3→2）。これがないと、Word は通常のスタイル付きテキストとして認識し、目次とナビゲーションウィンドウが機能しません。

複数テンプレートのマージ： 複数のテンプレートファイル（フォント、見出し、区切り）が指定された場合は、まず references/scenario_c_apply_template.md の「Multi-Template Merge」セクションを読んでください。主なルール：

• すべてのテンプレートのスタイルを 1 つの styles.xml に統合します。構成（セクション／区切り）は区切りテンプレートから取得します。
• 各コンテンツ段落は必ず 1 回だけ配置します。セクション区切りの挿入時に重複させてはいけません。
• 埋め合わせやセクション区切りとして、空の段落を絶対に挿入しないでください。出力の段落数は入力と同じにします。見た目の間隔には、セクション区切りプロパティ（w:pPr 内の w:sectPr）とスタイルの間隔（w:spacing の前後）を使用します。
• 最初の章だけでなく、すべての章見出しの前に oddPage セクション区切りを挿入します。章に二段組のコンテンツがある場合も、必ず oddPage で開始します。段組を切り替えるには、見出しの後に 2 つ目の連続セクション区切りを使用します。
• 二段組の章には、3 つのセクション区切りが必要です：（1）直前の段落の pPr に oddPage、（2）章の見出しの pPr に continuous+cols=2、（3）最後の本文段落の pPr に continuous+cols=1 を指定して段組を戻します。
• 各セクションの titlePg 設定を区切りテンプレートからコピーします。要旨と目次のセクションでは、通常 titlePg=true が必要です。

複数セクションのヘッダー／フッター： セクションが 10 個以上あるテンプレート（中国語の論文など）では、セクションごとにヘッダー／フッターが異なります（ローマ数字とアラビア数字のページ番号、領域ごとに異なるヘッダー テキストなど）。ルール：

• C-2 Base-Replace を使用します。テンプレートを出力のベースとしてコピーしてから、本文コンテンツを置き換えます。これにより、すべてのセクション、ヘッダー、フッター、titlePg の設定が自動的に保持されます。
• ヘッダー／フッターを一から作成してはいけません。テンプレートのヘッダー／フッター XML をバイト単位でそのままコピーします。
• テンプレートのヘッダー XML にない書式（罫線、配置、フォントサイズ）を追加してはいけません。
• 表紙以外のセクションには、ヘッダー／フッター XML ファイルを用意する必要があります（少なくとも空のヘッダーとページ番号のフッター）。
• references/scenario_c_apply_template.md の「Multi-Section Header/Footer Transfer」セクションを参照してください。

参考資料

必要に応じて読み込み、一度にすべて読み込まないでください。タスクに最も関連するファイルを選びます。

以下の C# サンプルと設計資料は、プロジェクトのナレッジベース（「百科事典」）です。 OpenXML コードを書くときは、必ず最初に関連するサンプルファイルを読んでください。コンパイル可能で SDK バージョンで検証済みのパターンが記載されており、よくあるエラーを防げます。デザイン上の判断を行うときは、デザイン原則とレシピのファイルを読んでください。これらには、推測ではなく、信頼できる情報源（IEEE、ACM、APA、Nature など）に基づいて検証された、調和の取れたパラメーターセットがまとめられています。

シナリオガイド（各パイプラインの開始時にお読みください）

ファイル	対象
references/scenario_a_create.md	パイプライン A：ゼロから作成する
references/scenario_b_edit_content.md	パイプライン B：既存のコンテンツを編集する
references/scenario_c_apply_template.md	パイプライン C：テンプレートの書式を適用する

C# コードサンプル（コンパイル可能で、詳細なコメント付き — コード作成時にお読みください）

ファイル	トピック
Samples/DocumentCreationSamples.cs	ドキュメントのライフサイクル：作成、開く、保存、ストリーム、ドキュメントの既定値、設定、プロパティ、ページ設定、複数セクション
Samples/StyleSystemSamples.cs	スタイル：Normal／Heading の階層、文字・表・リストのスタイル、DocDefaults、latentStyles、CJK 公文、APA 第7版、インポート、継承の解決
Samples/CharacterFormattingSamples.cs	RunProperties：フォント、サイズ、太字／斜体、すべての下線、色、ハイライト、取り消し線、下付き／上付き、大小文字、文字間隔、網かけ、罫線、強調記号
Samples/ParagraphFormattingSamples.cs	ParagraphProperties：配置、インデント、行間／段落間隔、段落の分割禁止／孤立行、アウトラインレベル、罫線、タブ、番号付け、双方向テキスト、フレーム
Samples/TableSamples.cs	表：罫線、グリッド、セルのプロパティ、余白、行の高さ、ヘッダーの繰り返し、セルの結合（水平＋垂直）、ネスト、浮動、三線表、しま模様
Samples/HeaderFooterSamples.cs	ヘッダー／フッター：ページ番号、「全 X ページ中の Y ページ目」、先頭／偶数／奇数ページ、ロゴ画像、表レイアウト、公文の「-X-」、セクションごとの設定
Samples/ImageSamples.cs	画像：行内、浮動、テキストの折り返し、罫線、代替テキスト、ヘッダー／表内、置換、SVG のフォールバック、寸法の計算
Samples/ListAndNumberingSamples.cs	番号付け：箇条書き、複数レベルの10進番号、カスタム記号、アウトラインから見出しへの変換、法律文書、中国語の 一／（一）／1.／(1)、再開／継続
Samples/FieldAndTocSamples.cs	フィールド：目次、SimpleField と複合フィールドの比較、DATE／PAGE／REF／SEQ／MERGEFIELD／IF／STYLEREF、目次スタイル
Samples/FootnoteAndCommentSamples.cs	脚注、文末脚注、コメント（4ファイルシステム）、ブックマーク、ハイパーリンク（内部＋外部）
Samples/TrackChangesSamples.cs	変更履歴：挿入（w:t）、削除（w:delText!）、書式変更、すべての変更の承認／却下、移動履歴
Samples/AestheticRecipeSamples.cs	信頼できる情報源に基づく13種類の美しい書式レシピ：ModernCorporate、AcademicThesis、ExecutiveBrief、ChineseGovernment（GB/T 9704）、MinimalModern、IEEE Conference、ACM sigconf、APA 第7版、MLA 第9版、Chicago/Turabian、Springer LNCS、Nature、HBR — それぞれ公式スタイルガイドに基づく正確な値を収録

注：Samples/ のパスは scripts/dotnet/MiniMaxAIDocx.Core/ からの相対パスです。

Markdown リファレンス（仕様やデザインルールが必要なときに参照してください）

ファイル	参照するタイミング
references/openxml_element_order.md	XML 要素の順序ルール（破損を防止）
references/openxml_units.md	単位変換：DXA、EMU、ハーフポイント、8 分の 1 ポイント
references/openxml_encyclopedia_part1.md	詳細な C# 百科事典：ドキュメントの作成、スタイル、文字と段落の書式設定
references/openxml_encyclopedia_part2.md	詳細な C# 百科事典：ページ設定、表、ヘッダー／フッター、セクション、ドキュメントのプロパティ
references/openxml_encyclopedia_part3.md	詳細な C# 百科事典：目次、脚注、フィールド、変更履歴、コメント、画像、数式、番号付け、保護
references/typography_guide.md	フォントの組み合わせ、サイズ、間隔、ページレイアウト、表のデザイン、配色
references/cjk_typography.md	CJK フォント、字号のサイズ、RunFonts のマッピング、GB/T 9704 公文規格
references/cjk_university_template_guide.md	中国の大学論文テンプレート：数値の styleId（1/2/3 と Heading1 の違い）、ドキュメント構成（表紙→要旨→目次→本文→参考文献）、フォントの要件、よくある誤り
references/design_principles.md	デザインの基本原則：6 つのデザイン原則（余白、コントラスト／スケール、近接、整列、反復、階層）— WHAT だけでなく WHY も解説
references/design_good_bad_examples.md	良い例と悪い例の比較：OpenXML の値、ASCII モックアップ、修正方法を含む、タイポグラフィのミス 10 分類
references/track_changes_guide.md	変更履歴の詳細な解説
references/troubleshooting.md	症状に応じた修正方法：画面上で見られる症状（見出しがおかしい、画像が表示されない、目次が壊れているなど）から検索できる、よくある問題 13 件 — 症状を検索して修正方法を確認できます