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# パス

タスクで構造的なドキュメント操作が必要な場合 (カスタムスタイル、複雑なテーブル、複数セクションレイアウト、ヘッダー/フッター、TOC、画像)、CLI の制限と戦うのではなく、C# を直接書きます。このスカフォルドを使用してください:

// File: scripts/dotnet/task.csx  (または Console プロジェクト内の新しい .cs)
// 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());

// --- ここにロジックを記述 ---
// 関連する Samples/*.cs ファイルを最初に読む (テスト済みパターン)
// 下の参考文献セクションの Samples テーブルを参照してください

C# を書く前に、関連する Samples/*.cs ファイルを読んでください — コンパイル可能で SDK バージョン検証済みのパターンが含まれています。下の参考文献セクションの Samples テーブルはトピックとファイルのマッピングです。

CLI の略記

下の CLI コマンドはすべて $CLI を以下の略記として使用します:

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

パイプラインルーティング

確認してルーティング: ユーザーが入力 .docx ファイルを持っていますか?

ユーザータスク
├─ 入力ファイルなし → パイプライン A: 作成
│   シグナル: "write", "create", "draft", "generate", "new", "make a report/proposal/memo"
│   → references/scenario_a_create.md を読む
│
└─ 入力 .docx あり
    ├─ コンテンツの置換・記入・修正 → パイプライン B: 記入-編集
    │   シグナル: "fill in", "replace", "update", "change text", "add section", "edit"
    │   → references/scenario_b_edit_content.md を読む
    │
    └─ 再フォーマット・スタイル適用・テンプレート適用 → パイプライン C: フォーマット適用
        シグナル: "reformat", "apply template", "restyle", "match this format", "套模板", "排版"
        ├─ テンプレートがスタイルのみ (コンテンツなし) → C-1: オーバーレイ (ソースにスタイル適用)
        └─ テンプレートに構造がある (カバー/TOC/例セクション) → C-2: ベース置換
            (テンプレートをベースとして使用、例コンテンツをユーザーコンテンツで置換)
        → references/scenario_c_apply_template.md を読む

リクエストが複数のパイプラインにまたがる場合は、順序に実行します (例: 作成してからフォーマット適用)。

前処理

必要に応じて .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
• 構造的 (カスタムスタイル、複数セクション、TOC、画像、複雑なテーブル): 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"}'

その後、検証パイプライン を実行します。また diff を実行して変更が最小限であることを確認:

$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

ゲートチェックは ハード要件 です。パスするまでは配信しません。失敗した場合: 診断、修正、再実行。

また diff を実行してコンテンツ保持を確認: $CLI diff --before source.docx --after out.docx

検証パイプライン

すべての書き込み操作の後に実行します。シナリオ C の場合、完全なパイプラインは 必須 です。A/B の場合は 推奨 です (操作が自明に単純な場合のみスキップ)。

$CLI merge-runs --input doc.docx                                    # 1. ラン統合
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd     # 2. XSD 構造
$CLI validate --input doc.docx --business                           # 3. ビジネスルール

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
# 確認: フォント汚染=0、テーブル数が正確、描画数が正確、sectPr 数が正確

最終プレビュー: 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 インチ = 1440、1cm ≈ 567)。

見出しスタイルは OutlineLevel を必須: 見出しスタイル (Heading1、ThesisH1 など) を定義する際は、常に StyleParagraphProperties に new OutlineLevel { Val = N } を含めます (H1→0、H2→1、H3→2)。これがないと、Word はそれらを通常のスタイル付きテキストと見なし — TOC とナビゲーションペインが機能しません。

複数テンプレートマージ: 複数のテンプレートファイル (フォント、見出し、改ページ) が与えられた場合、まず references/scenario_c_apply_template.md セクション「Multi-Template Merge」を読みます。重要ルール:

• すべてのテンプレートのスタイルを 1 つの styles.xml にマージします。構造 (セクション/改ページ) は改ページテンプレートから取得します。
• 各コンテンツ段落は厳密に 1 回だけ出現 — セクション改ページを挿入する際に重複させないでください。
• 出力段落数は入力と等しくする必要があります。セクション区切り (改ページプロパティ w:sectPr を w:pPr 内) とスタイル間隔 (w:spacing 前後) を視覚的な区切りに使用します。
• すべての章見出しの前に oddPage セクション改ページを挿入します (最初だけではなく)。章に二段落コンテンツがある場合でも、oddPage で始まる必要があります。見出し後の列切り替え用に 2 番目の連続改ページを使用します。
• 二段落章には 3 つのセクション改ページが必要: (1) 前の段落の pPr 内の oddPage、(2) 章見出しの pPr 内の連続+cols=2、(3) 最後の本文段落の pPr 内の連続+cols=1 で復帰。
• 改ページテンプレートから各セクションの titlePg 設定をコピーします。抄録と TOC セクションは通常 titlePg=true が必要です。

複数セクションヘッダー/フッター: 10+ セクション (例: 中国の論文) のテンプレートはセクションごとに異なるヘッダー/フッター (ローマ数字 vs アラビア数字のページ番号、ゾーンごとに異なるヘッダーテキスト) があります。ルール:

• C-2 ベース置換を使用: テンプレートを出力ベースとしてコピーしてから、本文コンテンツを置換します。これはすべてのセクション、ヘッダー、フッター、titlePg 設定を自動的に保持します。
• ヘッダー/フッターをゼロから再作成しないでください — テンプレートヘッダー/フッター XML を byte-for-byte でコピーしてください。
• テンプレートヘッダー 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 7th、インポート、継承解決
Samples/CharacterFormattingSamples.cs	RunProperties: フォント、サイズ、太字/斜体、すべての下線、色、ハイライト、打ち消し、上付き/下付き、大文字、間隔、網掛け、罫線、強調マーク
Samples/ParagraphFormattingSamples.cs	ParagraphProperties: 配置、インデント、行/段落間隔、keep/widow、アウトラインレベル、罫線、タブ、番号付け、bidi、フレーム
Samples/TableSamples.cs	テーブル: 罫線、グリッド、セルプロパティ、マージン、行高さ、ヘッダー繰り返し、マージ (H+V)、ネスト、浮動、三線表 三线表、ゼブラストライピング
Samples/HeaderFooterSamples.cs	ヘッダー/フッター: ページ番号、「ページ X / Y」、最初/偶数/奇数、ロゴ画像、テーブルレイアウト、公文「-X-」、セクションごと
Samples/ImageSamples.cs	画像: インライン、浮動、テキスト折り返し、罫線、代替テキスト、ヘッダー/テーブル内、置換、SVG フォールバック、寸法計算
Samples/ListAndNumberingSamples.cs	番号付け: 箇条書き、複数レベル 10 進数、カスタムシンボル、アウトライン→見出し、法律、中文 一/（一）/1./(1)、再開/続行
Samples/FieldAndTocSamples.cs	フィールド: TOC、SimpleField vs 複合フィールド、DATE/PAGE/REF/SEQ/MERGEFIELD/IF/STYLEREF、TOC スタイル
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 7th、MLA 9th、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# 百科事典: TOC、脚注、フィールド、変更追跡、コメント、画像、数学、番号付け、保護
references/typography_guide.md	フォントペアリング、サイズ、間隔、ページレイアウト、テーブル設計、配色スキーム
references/cjk_typography.md	CJK フォント、字号 サイズ、RunFonts マッピング、GB/T 9704 公文 標準
references/cjk_university_template_guide.md	中国の大学論文テンプレート: 数値 styleIds (1/2/3 vs Heading1)、ドキュメントゾーン構造 (表紙→抄録→TOC→本文→参考文献)、フォント期待値、一般的な間違い
references/design_principles.md	美学の基礎: 6 つの設計原則 (空白、コントラスト/スケール、近接、配置、反復、階層) — "何" ではなく "なぜ" を教えます
references/design_good_bad_examples.md	良い例と悪い例の比較: 10 カテゴリーのタイポグラフィー間違い (OpenXML 値、ASCII モックアップ、修正を含む)
references/track_changes_guide.md	リビジョンマーク深掘り
references/troubleshooting.md	症状駆動の修正: 13 の一般的な問題 (見出しが正しくない、画像が見つからない、TOC が壊れているなど) — 症状で検索、修正を見つけます