kimi-docx

パート 1：目標

⚠️ 解凍する場合と読み取る場合

ソース文書の書式を少しでも保持するには、必ず ZIP を解凍して XML を解析してください。

Read ツールが返すのはプレーンテキストのみです。フォント、色、配置、罫線、スタイルは失われます。

必要なもの	方法
テキスト内容のみ（要約、分析、翻訳）	Read ツールで問題ありません
書式情報（スタイルのコピー、レイアウトの保持、テンプレートへの入力）	解凍して XML を解析
構造とコメント／変更履歴	pandoc input.docx -t markdown

基本原則

1. 書式を保持する — 既存の文書を編集する場合は、元の書式を維持してください。複製して変更し、作り直してはいけません。

2. 機能を正しく実装する — コメントでは複数ファイル間の同期が必要です。変更履歴ではリビジョンマークが必要です。適切な構造を使用してください。

代替手段として python-docx/docx-js を決して使用しないでください。 これらのライブラリは、XML を直接操作する場合よりも品質の低い出力を生成します。

ソースの原則

テンプレートが提供されている場合＝デザイナーではなく、フォーム入力担当者として作業します。

• 書式はユーザーが決めます
• タスク：プレースホルダーを置き換える。再デザインはしない
• PDF フォームへの入力と同じです。再デザインしてはいけません

テンプレートがない場合＝デザイナーとして作業します。 シナリオに応じて自由にデザインしてください。

.doc（旧形式）の場合は、まず libreoffice --headless --convert-to docx で変換してください。

---

パート 2：実行

ファイル構成

docx/
├── SKILL.md                      ← This file (entry point + reference)
├── references/
│   └── EditingGuide.md           → Complete Python editing tutorial (comments, track changes, 5-file sync)
├── scripts/
│   ├── docx                      → Unified entry (the only script to call)
│   ├── fix_element_order.py      → Auto-fix XML element ordering
│   ├── validate_docx.py          → Business rule validation
│   ├── generate_backgrounds.py       → Morandi style backgrounds
│   ├── generate_inkwash_backgrounds.py → Ink-wash style backgrounds
│   └── generate_chart.py         → matplotlib (only for heatmaps/3D/radar; simple charts must use native)
├── assets/
│   └── templates/
│       ├── KimiDocx.csproj       → Project file template (for creating new docs)
│       ├── Program.cs            → Program entry template
│       ├── Example.cs            → Complete example (cover+TOC+charts+back cover)
│       ├── CJKExample.cs         → CJK content patterns (quote escaping, fonts)
│       └── xml/                  → XML templates for comments infrastructure
└── validator/                    → OpenXML validator (pre-compiled binary, AI does not modify)

新しい文書を作成する場合：C# SDK と ./scripts/docx build を使用します → パターンについては Example.cs、CJK コンテンツについては CJKExample.cs を参照してください
既存の文書を編集する場合：Python + lxml を使用します → 詳細なチュートリアルについては references/EditingGuide.md を参照してください

⚠️ これらの方法を混在させないでください。 作成には C# SDK、編集には Python を使用します。python-docx/docx-js は決して使用しないでください。

環境のセットアップ

初回は、SKILL ディレクトリで次を実行してください。

cd /app/.kimi/skills/kimi-docx/
./scripts/docx init

固定パス規約（変更不可）：

パス	用途
/app/.kimi/skills/kimi-docx/	コマンドを実行する SKILL ディレクトリ
/tmp/docx-work/	作業ディレクトリ。ここで Program.cs を編集します
/mnt/okcomputer/output/	出力ディレクトリ。最終成果物を保存します
/mnt/okcomputer/upload/	ユーザーのアップロード場所（入力ファイル）

スクリプトコマンド（./scripts/docx <cmd>）：

コマンド	用途
env	環境の状態を表示します（変更なし）
init	依存関係とワークスペースをセットアップします
build [out]	コンパイル、実行、検証を行います（デフォルト：output/output.docx）
validate FILE	既存の docx を検証します

スクリプトは次の処理を自動的に行います。

• dotnet/python3（必須）、pandoc/playwright/matplotlib（任意）を検出します
• インストール済みの場合はそのまま使用し、未インストールの場合は自動インストールし、破損している場合は修復します
• 作業ディレクトリを初期化し、テンプレートファイルをコピーします

ビルドプロセス

必ず ./scripts/docx build を使用してください。dotnet build && dotnet run を個別に実行しないでください（検証が省略されます）。

Program.cs の出力パス規約（重要）

ビルドスクリプトが生成ファイルを見つけられるよう、Program.cs はコマンドライン引数から出力パスを取得する必要があります。

// Correct - get output path from command line arguments
string outputFile = args.Length > 0 ? args[0] : "/mnt/okcomputer/output/output.docx";

// Wrong - hardcoded path causes build failure
string outputFile = "my_document.docx";  // Script can't find file!

手順	操作	備考
1. コンパイル	dotnet build	失敗時に修正案を提示します
2. 生成	dotnet run -- <output path>	パスはコマンドライン引数で渡します
3. 自動修正	fix_element_order.py	XML 要素の順序に関する問題を修正します
4. OpenXML 検証	validator/	必須
5. ビジネスルール	validate_docx.py	必須
6. 統計	文字数と単語数	任意（pandoc が必要）

検証は必須です：失敗してもファイルは保持されますが、警告が表示されます。エラーメッセージを確認して問題を修正してください。

単独での検証

cd /app/.kimi/skills/kimi-docx/
./scripts/docx validate /mnt/okcomputer/output/report.docx

コンテンツの検証（必須）

pandoc が唯一の信頼できる情報源です。 OpenXML バリデーターは構造を確認しますが、実際のコンテンツを表示するのは pandoc です。

納品前に、pandoc で次の点を確認してください。

• pandoc output.docx -t plain — テキストがすべて含まれていることを確認します
• リビジョン／コメントの場合：--track-changes=all を追加してマーカーの位置を確認します

⚠️ 重要：comments.xml が存在していても、コメントが表示されるとは限りません。件数が一致しない場合は、doc_tree が保存されていません。references/EditingGuide.md §5.3 を参照してください。

---

パート 3：品質基準

納品基準

ありきたりなスタイルと凡庸な見た目では、凡庸な納品物にしかなりません。

コンテンツ、機能性、スタイルを深く考慮し、スタジオ品質の Word 文書を作成してください。ユーザーは、高度な機能（表紙、目次、背景、裏表紙、脚注、グラフなど）を明示的に求めないことがよくあります。ニーズを深く理解し、積極的に拡張してください。

言語の統一

文書の言語 ＝ ユーザーとの会話の言語（ファイル名、本文、見出し、ヘッダー、目次のヒント、グラフのラベル、その他すべてのテキストを含みます）。

ヘッダーとフッター — デフォルトで必須

ほとんどの文書には、必ずヘッダーとフッターを含めてください。具体的なスタイル（配置、形式、内容）は、文書全体のデザインに合わせてください。

• ヘッダー：通常は文書タイトル、会社名、または章名です
• フッター：通常はページ番号です（形式は「X / Y」「Page X」「— X —」など、自由に設定できます）
• 表紙／裏表紙：TitlePage 設定を使用して、1 ページ目のヘッダー／フッターを非表示にします

プロフェッショナルな要素（重要）

ユーザーの期待を上回る文書を作成し、プロフェッショナルな要素を積極的に追加してください。ユーザーからの依頼を待たないでください。納品基準：2024 年におけるトップデザイナーのビジュアル品質。

表紙とビジュアル：

• 公式文書（提案書、報告書、財務書類、入札書類、契約書）／クリエイティブな文書（招待状、グリーティングカード）には、表紙と裏表紙が必要です
• 表紙には、デザイナー品質の背景画像を使用してください
• 見た目を向上させるため、本文ページにも背景を設定できます

構成：

• 長い文書（3 セクション以上）には目次を追加し、目次の後に更新を促すヒントを必ず追加してください

データの提示：

• データを比較したり傾向を示したりする場合は、テキストのみのリストではなく、グラフを使用してください
• 表には薄い灰色のヘッダーまたは三線スタイルを使用し、Word のデフォルトの青色は避けてください

リンクと参照：

• URL はクリック可能なハイパーリンクにしてください
• 図／表が複数ある場合は、番号と相互参照（「図 1 を参照」「表 2 に示すとおり」）を追加してください
• 学術、法律、データ分析で引用が必要な場合は、対応する脚注／文末脚注と、クリックして移動できる正しい本文内参照を実装してください

目次の更新ヒント

Word の目次はフィールドコードであり、生成時のページ番号は不正確な場合があります。目次の後に灰色のヒントテキストを必ず追加し、手動で更新するようユーザーに伝えてください。

Table of Contents
─────────────────
Chapter 1 Overview .......................... 1
Chapter 2 Methods ........................... 3
...

(Hint: On first open, right-click the TOC and select "Update Field" to show correct page numbers)

ヒントテキストの要件：

• 目立たないデザインにすること — 灰色で小さめのフォントサイズにし、目次の項目と競合しないようにします
• 言語：ユーザーとの会話の言語に合わせます

ユーザーから明示的に求められた場合のみ

機能	理由
透かし	見た目が変わります。SDK の制限：VML の透かしクラスは正しくシリアライズされないため、ヘッダーに生の XML を書き込む必要があります。
文書の保護	編集を制限します
差し込み印刷フィールド	データソースが必要です

グラフ選択の方針（重要）

デフォルトでは、編集可能でファイルサイズの小さいネイティブ Word グラフを使用してください。

グラフの種類	方法	備考
円グラフ	ネイティブ	Example.cs → AddPieChart()
棒グラフ	ネイティブ	Example.cs → AddBarChart()
折れ線グラフ	ネイティブ	棒グラフの構造を参考にして、c:lineChart を使用します
横棒グラフ	ネイティブ	棒グラフの構造を参考にして、barDir="bar" を使用します
ヒートマップ、3D、レーダーチャート	matplotlib	Word のネイティブ機能では対応していません
複雑な統計グラフ（箱ひげ図など）	matplotlib	Word のネイティブ機能では対応していません

ネイティブグラフが推奨されます（編集可能で、ファイルサイズが小さいため）が、データ分析の用途では matplotlib も使用できます。

画像／グラフの挿入

PNG（matplotlib のグラフ、背景、写真）は、必ず AddInlineImage() を使用して挿入します。

AddInlineImage(body, mainPart, "/path/to/image.png", "Description", docPrId++);

重要：

• グラフのラベル／タイトルは、ドキュメントの言語に合わせる必要があります（例：中国語のドキュメントには中国語のラベル）
• ビルド出力に X images と表示されます。0 の場合、画像は挿入されていません

コンテンツの制約

単語数／ページ数の要件

ユーザーの依頼	実行基準
指定された単語数（例：「3000 words」）	実際の出力を±20％以内にする
指定されたページ数（例：「5 pages」）	正確に一致させる
範囲の指定（例：「2000-3000 words」）	範囲内に収める
最低数の指定（例：「at least 5000 words」）	要件の2倍を超えない

禁止事項：箇条書きのリストを過剰に使って単語数を水増ししないでください。情報密度を保ってください。

アウトラインの遵守

• ユーザーがアウトラインを提示している場合：厳密に従い、追加、削除、並べ替えを行わないでください
• アウトラインが提示されていない場合：標準的な構成を使用します
  • 学術：序論 → 文献 → 方法 → 結果 → 考察 → 結論
  • ビジネス：エグゼクティブサマリー → 分析 → 提言
  • 技術：概要 → 原則 → 使用方法 → 例 → FAQ

シナリオに必要な要素の網羅

ユーザーの次の行動を見越し、シナリオに必要な要素を補完してください。以下の例に限らず、あらゆるドキュメント種別にこの原則を適用してください。

• 試験問題 → 氏名／クラス／ID の記入欄、各設問の配点（合計も考慮）、採点欄
• 契約書 → 両当事者の署名・押印欄、日付、契約番号、添付書類一覧
• 議事録 → 出席者、欠席者、担当者付きのアクション項目、次回会議の日時

デザイン方針

配色

彩度を抑えた色調を使い、Word の既定の青色や matplotlib の既定の高彩度色は避けてください。

ドキュメントのシナリオに応じて、柔軟に配色を選んでください。

スタイル	配色	適したシナリオ
モランディ	柔らかく落ち着いた色調	芸術、編集
アースカラー	茶色、オリーブ色、自然な色	環境、オーガニック
北欧	クールグレー、霧がかった青	ミニマリスト、テクノロジー
日本の侘び寂び	グレー、無垢材、禅	伝統、思索
フランスのエレガンス	オフホワイト、くすんだピンク	高級、フェミニン
インダストリアル	チャコール、さび色、コンクリート	製造、エンジニアリング
学術	ネイビー、バーガンディ、アイボリー	研究、教育
オーシャンミスト	霧がかった青、砂色	海洋、ウェルネス
フォレストモス	オリーブ色、モスグリーン	自然、サステナビリティ
砂漠の夕暮れ	黄土色、砂金色	温暖、地域性

同じドキュメント内では配色を統一してください。

レイアウト

余白（ページ余白、段落間隔）を確保し、明確な階層（H1 > H2 > 本文）を設け、適切なパディングを設定します（テキストが枠線に触れないようにします）。

ページ分割の制御

Word は固定ページではなく、フローレイアウトを使用します。以下のプロパティでページ分割を制御します。

プロパティ	XML	効果
次の段落と分離しない	<w:keepNext/>	見出しを次の段落と同じページに配置する
段落内で改ページしない	<w:keepLines/>	段落がページをまたいで分割されないようにする
段落前で改ページ	<w:pageBreakBefore/>	新しいページから開始する（H1 用）
段落の孤立行制御	<w:widowControl/>	ページの先頭／末尾に行が1行だけ残るのを防ぐ

// Example: H1 always starts on new page, stays with next paragraph
new ParagraphProperties(
    new ParagraphStyleId { Val = "Heading1" },
    new PageBreakBefore(),
    new KeepNext(),
    new KeepLines()
)

表のページ分割：

// Allow row to break across pages (avoid large blank areas)
new TableRowProperties(
    new CantSplit { Val = false }  // false = can split
)

// Repeat header row on each page
new TableRowProperties(
    new TableHeader()
)

---

パート4：技術リファレンス

作業内容に応じて選択してください：

作業	技術スタック	リファレンス
新しいドキュメントの作成	C# + OpenXML SDK	4.1-4.6 + Example.cs
既存ドキュメントの編集	Python + lxml	4.7 + references/EditingGuide.md

---

4.1 SDK の基礎

スキーマへの準拠（必ず覚えてください）

OpenXML には厳密な要素の順序要件があります。順序が間違っていると、Word でファイルを開けません。

必須スタイル

// Normal style must exist - all Heading styles use basedOn="Normal"
styles.Append(new Style(
    new StyleName { Val = "Normal" },
    new StyleParagraphProperties(
        new SpacingBetweenLines { After = "200", Line = "276", LineRule = LineSpacingRuleValues.Auto }
    ),
    new StyleRunProperties(
        new RunFonts { Ascii = "Calibri", HighAnsi = "Calibri" },
        new FontSize { Val = "22" },
        new FontSizeComplexScript { Val = "22" }
    )
) { Type = StyleValues.Paragraph, StyleId = "Normal", Default = true });

要素の順序に関するルール

順序に関する問題のほとんどは、fix_element_order.py で自動修正されます。覚えておくべき主なルールは次のとおりです。

親要素	主なルール
sectPr	headerRef → footerRef は pgSz → pgMar より前に置く必要があります
Table	tblPr と tr の間に tblGrid が必要です（下記参照）

テーブルには tblGrid が必要です

// Correct - table must define grid
var table = new Table();
table.Append(new TableProperties(...));
table.Append(new TableGrid(           // Required!
    new GridColumn { Width = "4680" },
    new GridColumn { Width = "4680" }
));
table.Append(new TableRow(...));

// Wrong - missing tblGrid, Word cannot open
var table = new Table();
table.Append(new TableProperties(...));
table.Append(new TableRow(...));  // Adding rows directly

テーブルの列幅の整合性

テーブルが歪む主な原因は、tblPr の gridCol の幅がセルの tcW の幅と一致しないことです。

// Correct - gridCol and tcW match exactly
table.Append(new TableGrid(
    new GridColumn { Width = "3600" },  // First column
    new GridColumn { Width = "5400" }   // Second column
));

var row = new TableRow(
    new TableCell(
        new TableCellProperties(
            new TableCellWidth { Width = "3600", Type = TableWidthUnitValues.Dxa }  // Matches gridCol!
        ),
        new Paragraph(new Run(new Text("Content")))
    ),
    new TableCell(
        new TableCellProperties(
            new TableCellWidth { Width = "5400", Type = TableWidthUnitValues.Dxa }  // Matches gridCol!
        ),
        new Paragraph(new Run(new Text("Content")))
    )
);

ルール	理由
gridCol の数 = テーブルの列数	そうでない場合、列幅の計算に失敗します
gridCol.Width = tcW.Width	不一致があると歪みが発生します（検証時にチェックされます）
同じ列のすべての行で同じ tcW を使用する	列幅の整合性を維持します

値の上限

• paraId は 0x80000000 未満である必要があります（コメント段落 ID 用）

新規作成と編集

タスク	方法	理由
新しいドキュメントを作成する	C# OpenXML SDK	パッケージ構造、rels、Content_Types を自動的に処理します
既存のドキュメントを編集する	Python + lxml	透明性が高く、ブラックボックスがなく、完全に制御できます

新しいドキュメントを作成する場合：SDK を使った Example.cs のパターンを使用してください。

既存のドキュメントを編集する場合：Python のワークフロー全体については、references/EditingGuide.md を参照してください。

---

Example.cs

個々の関数だけでなく、全体の構造を理解するために、ファイル全体を読んでください。このファイルでは、各セクションがどのようにつながるか（表紙 → 目次 → 本文 → 裏表紙）が示されています。

Example 内の「Project Proposal」、「[Company Name]」などはサンプルコンテンツのみを示しており、配色も参考用のみです。

学ぶべきこと	学ぶべきでないこと
セクションの分割（表紙 → 目次 → 本文 → 裏表紙）	特定の色の値
背景を浮動配置するためのコード	サンプル内のビジネスコンテンツ
グラフ作成 API の呼び出し	サンプル内のコピーや文言
スタイル定義の構造	サンプル内のハードコードされたデータ

⚠️ Example の配色をコピーしないでください。 一流のデザイナーのように、ドキュメントの用途に基づいてビジュアルスタイルを再設計してください。

関数インデックス（実装の詳細はソースを参照してください）：

機能	関数	行番号
ドキュメント構造
スタイル（Normal、Heading1-3）	AddStyles()	85-203
表紙	AddCoverSection()	369-453
目次	AddTocSection()	458-526
本文セクション	AddContentSection()	531-729
裏表紙	AddBackcoverSection()	734-794
ビジュアル要素
浮動背景	CreateFloatingBackground()	228-279
比率を保ったインライン画像	AddInlineImage()	285-364
テーブル
三本線テーブル	CreateDataTable()	853-888
ヘッダー行（グレー背景）	CreateSimpleHeaderRow()	933-971
データ行	CreateSimpleDataRow()	976-1008
グラフ
円グラフ	AddPieChart()	1013-1049
棒グラフ	AddBarChart()	1133-1169
ページ要素
背景付きヘッダー	AddContentSection() 内	534-575
ページ番号付きフッター	AddContentSection() 内	578-588
ページ番号フィールド	CreatePageNumberField()	1345-1354
総ページ数フィールド	CreateTotalPagesField()	1356-1365
高度な機能
脚注	AddFootnote()	1370-1410
相互参照	CreateCrossReference()	1415-1425
番号付け／リスト	CreateBasicNumbering()	1327-1340

CJKExample.cs

CJK ドキュメントでは CJKExample.cs のみを読んでください。代わりに Example.cs を読むと、エラー（フォント設定の不足、引用符のエスケープ）が発生します。次の処理に対応しています。

• 引用符のエスケープ（"" → \u201c \u201d）
• CJK フォント設定（SimHei、Microsoft YaHei）
• CJK テキストの段落インデント

構造は Example.cs と同じです。両方を読む必要はありません。

4.2 コンテンツ要素

フィールドコード

PAGE/NUMPAGES/DATE/TOC — 構造：FieldChar(Begin) → FieldCode(" PAGE ") → FieldChar(Separate) → Text → FieldChar(End)。結果はキャッシュされます。WPS は UpdateFieldsOnOpen をサポートしていません。

ブックマークと相互参照

ブックマークは位置を示します（対応する ID を持つ BookmarkStart/BookmarkEnd）。相互参照は REF フィールド（" REF bookmarkName \\h "）を介してリンクします。

注意点：ブックマークされたテキストを削除すると、ブックマークも削除され、「エラー！参照元が見つかりません」と表示されます。

4.3 ビジュアルデザイン

背景画像のデザイン

表紙／裏表紙には背景が必要です。背景画像には中央に白い余白を設け、彩度を低くしてください。背景画像にテキストを含めてはいけません。ユーザーが編集できるよう、テキストは Word で実装してください。

デザインの流れ

1. 例を読む：HTML/CSS の手法（radial-gradient、transparency、positioning）について、scripts/generate_backgrounds.py を読んでください
2. 方向性を選ぶ：文書の用途に基づき、以下の表からスタイルの方向性を選択してください
3. オリジナルを作成する：例は 1 つのスタイルを示しているだけです。新しい HTML/CSS を最初から作成し、異なるデザインにしてください

⚠️ **例のコピー＝すべての文書が同じ見た目＝平凡な成果物。**各文書には、その内容と目的に合った独自のビジュアルアイデンティティが必要です。

スタイルの参考例

スタイル	主な要素	用途
MUJI	細い罫線＋余白	ミニマリスト、日本、ライフスタイル
Bauhaus	散在する幾何学模様	芸術、デザイン、クリエイティブ
Swiss Style	グリッド線＋アクセントバー	プロフェッショナル、企業
Soft Blocks	柔らかな色の長方形、重なり合う透明な図形	温かみ、教育、医療
Rounded Geometry	角丸の長方形、ピル形状	テクノロジー、インターネット、若々しさ
Frosted Glass	ぼかし＋透明感＋控えめな罫線	モダン、高級感、テクノロジー
Gradient Ribbons	柔らかなグラデーションの楕円＋小さなドット	フェミニン、美容、ソフト
Dot Matrix	規則的なドットパターンのテクスチャ	技術、データ、エンジニアリング
Double Border	入れ子状の罫線＋角の装飾	伝統的、フォーマル、法律
Waves	下部の SVG 波形＋グラデーション背景	海洋、環境、流動感
Warm Natural	アースカラー＋有機的な形状	環境、農業、自然

技術面：Playwright で 794×1123px（device_scale_factor=2）の画像を生成し、BehindDoc=true のフローティング Anchor として挿入します。Example.cs:CreateFloatingBackground() を参照してください。

レターヘッド（ビジネス文書）

正式なビジネス文書では、ヘッダー領域にレターヘッドを追加することを検討してください。よくあるパターン：

• 1 ページ目に完全なレターヘッドを配置（ロゴ＋会社名＋連絡先情報）し、2 ページ目以降は簡略化するか、非表示にします
• SectionProperties で TitlePage を使用して、1 ページ目と異なるヘッダーを有効にします
• 特定のビジネスの状況に応じて柔軟にデザインしてください。固定ルールはありません

2 段組みレイアウト

Columns を指定した sectPr を使用します。次の sectPr まで、セクション全体に適用されます。

4.4 特殊なコンテンツ

数式（OMML）

基本パターン：<m:e> は汎用のコンテンツコンテナーです。ほとんどすべての要素がコンテンツを <m:e> で囲みます。

テキスト：常に <m:r><m:t>text</m:t></m:r> を使い、テキストを直接記述しないでください。

ルート：インラインの場合は <m:oMath>、ディスプレイ数式の場合は <m:oMathPara> を使います。<m:oMath> を別の <m:oMath> の中にネストしないでください。

構造の例：

要素	構造
分数	<m:f><m:num><m:e>…</m:e></m:num><m:den><m:e>…</m:e></m:den></m:f>
下付き文字	<m:sSub><m:e>base</m:e><m:sub><m:e>…</m:e></m:sub></m:sSub>
上付き文字	<m:sSup><m:e>base</m:e><m:sup><m:e>…</m:e></m:sup></m:sSup>
根号	<m:rad><m:deg><m:e>n</m:e></m:deg><m:e>radicand</m:e></m:rad>
行列	<m:m><m:mr><m:e>cell</m:e><m:e>cell</m:e></m:mr></m:m>
多重演算子（∑∫）	<m:nary><m:sub><m:e>…</m:e></m:sub><m:sup><m:e>…</m:e></m:sup><m:e>body</m:e></m:nary>
括弧	<m:d><m:dPr><m:begChr m:val="("/><m:endChr m:val=")"/></m:dPr><m:e>…</m:e></m:d>
方程式配列	<m:eqArr><m:e>eq1</m:e><m:e>eq2</m:e></m:eqArr>

注意点：行列のセルには <m:e> を使い、列のプロパティ用の <m:mc> は使いません。

C# 文字列内のカーリークォート

C# では " " は文字列の区切りとして扱われ、CS1003 が発生します。最も簡単な修正方法：文字列リテラル内でエスケープした通常の引用符 \" を使います。カーリークォートが必要な場合は、XML エンティティを使ってエンコードします。二重引用符には “ ”、単一引用符には ‘ ’ を使います。

中国語の引用符の処理 — パターンの全例については CJKExample.cs を参照してください。

// ❌ Wrong - Chinese quotes break compilation
new Text("请点击"确定"按钮")  // CS1003!

// ✓ Correct - use Unicode escapes
new Text("请点击\u201c确定\u201d按钮")

文字	Unicode	用途
"（左二重引用符）	\u201c	開き引用符
"（右二重引用符）	\u201d	閉じ引用符
'（左単一引用符）	\u2018	開き単一引用符
'（右単一引用符）	\u2019	閉じ単一引用符

⚠️ 逐語的文字列 @"" は使わないでください — 逐語的文字列では \u エスケープが機能しません。

// ❌ WRONG - @"" verbatim string, \u NOT escaped, outputs literal "\u201c"
string text = @"她说\u201c你好\u201d";  // Outputs: 她说\u201c你好\u201d

// ✓ CORRECT - regular string, \u IS escaped
string text = "她说\u201c你好\u201d";   // Outputs: 她说"你好"

// ✓ For long text, use + concatenation
string para = "第一段内容，" +
              "她说\u201c这是引用\u201d，" +
              "继续写第二段。";

単位

Twips は 1/20 pt です（11906 = A4 の幅）。フォントサイズにはハーフポイントを使います（24 = 12pt）。EMU は 914400/inch です。

4.5 ページレイアウト

画像サイズ

wp:extent と a:ext の Cx/Cy は一致している必要があります。縦横比を保って拡大縮小するには、PNG ヘッダー（バイト 16～23）から寸法を読み取り、cy = cx * height / width を計算します。

ページネーションの制御

タイトルやグラフの段落に KeepNext を追加して、タイトルがページ末尾に取り残されたり、グラフとキャプションが分離したりするのを防ぎます。

セクション区切り

pPr 内の sectPr は、セクションの最後の段落を示します。PageBreak と Continuous の組み合わせは空白ページの原因になるため避けてください。NextPage を使います。

目次（TOC）

WPS は UpdateFieldsOnOpen に対応していないため、フィールドコード構造を使って目次の項目を事前に入力する必要があります：FieldChar(Begin) → FieldCode(" TOC ...") → FieldChar(Separate) → プレースホルダー項目（ハイパーリンク付きテキストとページ番号）→ FieldChar(End)。Separate と End の間にあるプレースホルダー項目により、Word で目次がすぐに表示されます。正確なページ番号を取得するには、ユーザーが更新する必要があります。静的なテキスト段落で目次を模倣しないでください。フィールドコード構造を使わないと、更新できません。Example.cs:AddTocSection() を参照してください。

パラメーター：\o "1-3"（見出しレベル）、\h（ハイパーリンク）、\z（Web 表示でページ番号を非表示）、\u（アウトラインレベル）。

見出しには組み込みの Heading1／Heading2 スタイルを使う必要があります（カスタムスタイルは認識されません）。

配置とタイポグラフィ

CJK 本文：両端揃え＋2 文字分のインデント。英語：左揃え。表内の数値：右揃え。見出し：インデントなし。

4.6 ページ要素

ヘッダーとフッター

// 1. Create header part
var headerPart = mainPart.AddNewPart<HeaderPart>();
var headerId = mainPart.GetIdOfPart(headerPart);

headerPart.Header = new Header(
    new Paragraph(
        new ParagraphProperties(
            new ParagraphStyleId { Val = "Header" },
            new Justification { Val = JustificationValues.Center }
        ),
        new Run(new Text("Document Title"))
    )
);

// 2. Create footer part (with page numbers)
var footerPart = mainPart.AddNewPart<FooterPart>();
var footerId = mainPart.GetIdOfPart(footerPart);

var footerPara = new Paragraph(
    new ParagraphProperties(
        new Justification { Val = JustificationValues.Center }
    )
);
// PAGE field: Begin → FieldCode → Separate → Text → End
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
footerPara.Append(new Run(new FieldCode(" PAGE ")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }));
footerPara.Append(new Run(new Text("1")));  // Placeholder, updated on open
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
footerPara.Append(new Run(new Text(" / ") { Space = SpaceProcessingModeValues.Preserve }));
// NUMPAGES field (same structure)
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Begin }));
footerPara.Append(new Run(new FieldCode(" NUMPAGES ")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.Separate }));
footerPara.Append(new Run(new Text("1")));
footerPara.Append(new Run(new FieldChar { FieldCharType = FieldCharValues.End }));
footerPart.Footer = new Footer(footerPara);

// 3. Reference in SectionProperties
new SectionProperties(
    new HeaderReference { Type = HeaderFooterValues.Default, Id = headerId },
    new FooterReference { Type = HeaderFooterValues.Default, Id = footerId },
    new PageSize { Width = 11906, Height = 16838 },
    new PageMargin { Top = 1440, Right = 1440, Bottom = 1440, Left = 1440, Header = 720, Footer = 720 }
)

ヘッダー／フッターの種類：

種類	HeaderFooterValues	用途
デフォルト	.Default	奇数ページ（またはすべてのページ）
偶数	.Even	偶数ページ
先頭	.First	先頭ページ

先頭ページを別にする場合（表紙など）：sectPr に TitlePage() を追加します。

奇数ページと偶数ページを別にする場合：settings.xml に <w:evenAndOddHeaders/> を追加します。

脚注と文末脚注

セパレーターに関する注意点：FootnotesPart／EndnotesPart には、ユーザーの脚注を追加する前に Id=-1（Separator）と Id=0（ContinuationSeparator）を含める必要があります。これらがないと、Word で正しく描画されません。

<w:footnote w:type="separator" w:id="-1">
  <w:p><w:r><w:separator/></w:r></w:p>
</w:footnote>
<w:footnote w:type="continuationSeparator" w:id="0">
  <w:p><w:r><w:continuationSeparator/></w:r></w:p>
</w:footnote>

リスト

AbstractNum と NumberingInstance を含む NumberingDefinitionsPart が必要です。段落内の NumberingProperties を使って適用します。

複数レベルのリスト：複数の Level を含む AbstractNum を作成します。書式：Decimal、UpperLetter、LowerRoman、Bullet、ChineseCounting。

ハイパーリンク

プレーンテキストではなく、<w:hyperlink> 要素を使用する必要があります。 先にリレーションシップを作成します。

var relId = mainPart.AddHyperlinkRelationship(new Uri("https://example.com"), true).Id;
paragraph.Append(new Hyperlink(new Run(
    new RunProperties(new Color { Val = "0563C1" }, new Underline { Val = UnderlineValues.Single }),
    new Text("Click here")
)) { Id = relId })

グラフとビジュアライゼーション

要件	推奨	代替
データグラフ	Word ネイティブ	matplotlib PNG
フローチャート	DrawingML Shapes	テーブルレイアウト
イラスト	画像生成	画像検索

Word グラフ：NumberLiteral（Excel 不要）を使用し、色には DataPoint を使います。例を参照してください。

matplotlib：dpi=300、axes.unicode_minus=False を設定します。フォントとラベルはドキュメントの言語に合わせる必要があります。

4.7 編集操作（Python API）

コメントと変更履歴には docx_lib.editing を使用します。

from scripts.docx_lib.editing import (
    DocxContext,
    add_comment, reply_comment, resolve_comment, delete_comment,
    insert_paragraph, insert_text, propose_deletion,
    reject_insertion, restore_deletion, enable_track_changes
)

with DocxContext("input.docx", "output.docx") as ctx:
    # add_comment(ctx, para_text, comment, highlight=None)
    # - para_text: text to locate paragraph
    # - comment: comment content
    # - highlight: text to highlight (omit to highlight entire paragraph)
    add_comment(ctx, "M-SVI index", "Please define", highlight="M-SVI")
    insert_text(ctx, "The method", after="method", new_text=" and materials")

完全なガイド：references/EditingGuide.md

4.8 XML クイックリファレンス

テキスト書式（rPr）

<w:r>
  <w:rPr>
    <w:rFonts w:ascii="Times New Roman" w:eastAsia="SimSun"/>
    <w:sz w:val="24"/>  
    <w:b/><w:i/><w:u w:val="single"/>
    <w:color w:val="FF0000"/>
  </w:rPr>
  <w:t>text</w:t>
</w:r>

フォントサイズ：21=10.5pt、24=12pt、28=14pt、32=16pt、44=22pt

変更履歴の構造

<w:ins w:id="1" w:author="..." w:date="...">
  <w:r><w:rPr>...</w:rPr><w:t>text</w:t></w:r>
</w:ins>


<w:del w:id="2" w:author="..." w:date="...">
  <w:r><w:rPr>...</w:rPr><w:delText>text</w:delText></w:r>
</w:del>

重要：<w:ins> と <w:del> はどちらも <w:r> を囲みます。内部に配置するのではありません。削除には <w:t> の代わりに <w:delText> を使用します。

スキーマの制約

ルール	要件
RSID 値	8 桁の大文字の 16 進数：00A1B2C3
空白	先頭または末尾に空白がある場合は xml:space="preserve"
リビジョンの構造	<w:ins>／<w:del> は <w:r> を囲む必要があり、w:id 属性が必要です

---

完全な例：動作するコード全体は references/EditingGuide.md を参照してください。