fill-template

テンプレートの差し込み（メールマージ）

1つのマスターテンプレートとデータテーブルから、行ごとに1つずつ、差し込み済みコピーを複数作成します。変わる部分だけを置き換え、マスターのレイアウトとスタイルはそのまま維持します。対象はドキュメントの生成のみです。送信、投稿、署名は行いません。

対象範囲と振り分け

ユーザーがテンプレートを1つとリストを用意し、行ごとに差し込み済みコピーを作成したい場合、または差し込み済みのサンプル .docxから再利用可能なトークン化テンプレートを作成したい場合（extract_template）に、このスキルを使用します。単独のオーダーメイドのレターを作成する場合（ドキュメントを1つ編集するだけ）や、ホスト環境で別のドキュメント処理パイプラインが必須の場合は使用しないでください。.xlsxフォームの抽出は今回は対象外です。

ユーザーが提供する入力

1. マスターテンプレート — .docxのレターまたはフォーム、または.xlsxフォーム。1回の実行につきマスターは1つです。レイアウトとスタイルの正本となります。
2. データテーブル — .xlsxまたは.csv。出力1つにつき1行で、ヘッダー行を含みます。列には、変動する値（氏名、金額、日付、参照情報など）を指定します。
3. （任意）命名パターン — 各出力ファイルの名前の付け方です。例：Letter_{Name}。既定値は<template>_<row-number>です。

ワークフロー（この順序で実行）

ユーザーからマスターではなく入力済みのサンプルが渡された場合は、まず抽出（ステップ 0）を実行し、ext["mapping"] を表示してから、生成を開始する前に確認を待ちます。それ以外の場合はステップ 1 から開始します。

0. 入力済みの .docx から抽出する（任意の逆方向の手順）。 extract_template(src, out_dir, name=None) は <name>_tokenised.docx と <name>_data.csv を書き込み（name の既定値はソースのファイル名の拡張子を除いた部分）、レポートを返します。値が変わる箇所は、tokenise と同じラン認識型の置換を使って {{Token}} に変換されます。CSV には、繰り返し出現する各インスタンスにつき 1 行が含まれます。report["mapping"]（リテラル → トークン → 場所）と、report["uncertain"] の項目を表示します。これらの範囲は推測せず、リテラルのまま残されています。トークン名は、次の 5 つの型付きパターンからのみ決まります。 Dear の後 → Recipient、$… → Amount、INV-123 → InvoiceRef、12 Mar 2026 のような日付 → Date、ACME-0042 → AccountRef。重複する場合は Amount2 などになります。型に分類できない変化箇所はリテラルのまま残されます。汎用の Value1／Value2 による代替処理は実装されていません。そのようなフィールドには、手動で tokenise を使用してください。その後、抽出したテンプレートとスケルトンを使ってステップ 3 に進むか、ユーザーにマッピングを編集して再トークン化してもらいます。

   from fill_template import (
       read_content, tokenise, tokens_in, load_rows, generate, extract_template,
   )
   
   ext = extract_template("filled_letters.docx", "extracted")
   print(ext["mapping"])       # confirm-before-reuse digest
   print(ext["uncertain"])     # left literal; do not invent
   

1. マスターを分析する。 read_content(path) で読み込み、行ごとに変わる部分（名前、敬称、金額、日付、参照番号など）と、固定された定型文を特定します。read_content は、繰り返される段落のテキストを (×N) のカウント付きで 1 回だけ表示します。これは tokenise が置換する箇所の数です（例：本文とヘッダーの両方にある名前）。トークン化する内容や、適切なトークン名の付け方については、references/tokenising-guide.md を参照してください。

2. トークン化したテンプレートを提案する。 変化する各フレーズ → トークン名の mapping を作成し、プレーンなリストとしてユーザーに提示します（"Ms Jordan Lee → {{Name}}、$1,000,000 → {{Amount}}、…"）。可能であれば、トークン名はデータファイルの列見出しに合わせます。そうするとマッピングが自動化されます。

3. ユーザーに確認する。 提案するトークンを表示し（必要であれば、トークン化したテンプレートを保存して、そのテキストも表示し）、何かを生成する前に明示的な確認を待ちます。これはレビューのチェックポイントです。最初にテンプレートを正しく仕上げてから、一括生成します。

   from fill_template import (
       read_content, tokenise, tokens_in, load_rows, generate, extract_template,
   )
   
   print(read_content("Letter_master.docx"))                       # step 1
   
   rep = tokenise("Letter_master.docx",                            # step 2
                  "Letter_tokenised.docx",
                  [{"find": "Ms Jordan Lee", "token": "Name"},
                   {"find": "$1,000,000",    "token": "Amount"},
                   {"find": "01 Jul 2026",   "token": "EffectiveDate"},
                   {"find": "REF-0001",      "token": "Reference"}])
   # rep["not_found"] lists any phrase that wasn't located — fix those before generating.
   print(tokens_in("Letter_tokenised.docx"))
   

   tokenise は完全一致する各フレーズを見つけて {{Token}} に置換し、そのフレーズが含まれるラン／セルの書式を保持します（太字の数値は太字のままです）。トークンごとの一致数を報告し、見つからなかったフレーズにはフラグを立てるため、200 通のレターを生成する前に find テキストの入力ミスを検出できます。

4. データを読み込み、マッピングを確認する。 headers, rows = load_rows("recipients.xlsx")。トークンから列へのマッピングは、既定では トークン名 == 列見出し（大文字・小文字を区別しない）です。異なるものは上書きしてください。テンプレート内に列のないトークンがある場合、または特定の行で対応する列が空欄の場合は、推測せず、«MISSING: Token» フラグを表示します。

5. 行ごとにファイルを 1 つ生成する。

   report = generate(
       "Letter_tokenised.docx", rows,
       token_to_column={"Name": "Recipient"},   # only the ones whose token != column
       outdir="out",
       name_pattern="Letter_{Recipient}",
   )
   

   report には、書き込まれたすべてのファイル、スキップされた行（例：名前パターンの列がデータにない場合）、unmapped_tokens、ファイルごとの missing トークンが一覧表示されます。

6. 正確に結果を報告する。 生成したファイル数と保存先をユーザーに伝え、空欄に対処してからバッチを使えるよう、missing フラグと unmapped_tokens の項目をすべて提示します。出力されたものはすべて、送付前に人が確認するためのドラフトです。

トークン化と置換の仕組み

• トークンの構文は {{TokenName}} です（波括弧内のスペースは無視されます）。
• .docx — 置換はラン単位で行われます。値はトークンの先頭があるランに入り（その書式を引き継ぎます）、トークンがまたがるその他のランは切り詰められます。トークンの外にあるランはそのまま保持されます。本文、表（入れ子を含む）、ヘッダー／フッターのテキストがすべて対象です。
• .xlsx — すべてのシートのすべてのセルにあるトークンが置換されます。それ以外のセルの内容、数式、書式はすべて保持されます（openpyxl）。値を表示したい場所にトークンを入力します。たとえば、セル B5 に {{Name}} と入力します。
• データ内の日付はデフォルトで DD MMM YYYY として表示され、整数では末尾の .0 が省かれます。通貨や特定の数値形式にする場合は、データファイルで列の書式を設定してください — ヘルパーは渡された値をそのまま挿入します。
• 決して捏造しないでください。 行に対応する値がないトークンは «MISSING: Token» として書き込まれ、レポートに記録されます。データ（またはマッピング）を修正して再実行してください。空欄に値を捏造して手入力しないでください。

安全性

• ファイルのみ。 ドキュメントを生成します。送信、投稿、メール、署名、提出は一切行いません。
• 1回の実行につきマスターは1つ。 1つのバッチに異なるテンプレートを混在させないでください。
• マスターに合わせる。 提供されたテンプレートのレイアウトとスタイルを維持し、トークンのみを置き換えます。
• 一括生成の前に確認する。 バッチを生成する前に、トークン化したテンプレートとマッピングについて明示的な承認を得てください。
• すべての空欄を明示する。 すべての «MISSING:…» フラグと未マッピングのトークンを報告し、決して見えないように隠さないでください。

ファイル

• scripts/fill_template.py — エンジンです。extract_template（入力済みの .docx → テンプレート＋スケルトン）・ read_content（分析）・tokenise / tokens_in・load_rows（.xlsx/.csv）・generate（行ごとに1ファイル＋レポート）を実行します。generate は、行辞書のリスト、または load_rows が返す (headers, rows) タプルを受け取ります。
• references/tokenising-guide.md — トークンの選び方と名前の付け方、書簡とフォームの違い、確認手順、MISSING フラグのルールを説明します。
• examples/example-run.md — 最初から最後までの実行例です（マスターとデータはご自身で用意してください。バイナリファイルは同梱されていません）。

原則

• 助言ではなくドラフト — 出力は人が確認するためのドラフトであり、完成した文書ではありません。
• 決して捏造しない — 値がない場合は、空欄のままにしたり推測したりせず、«MISSING: Token» フラグで明示します。
• 重要な処理は決定論的に — トークン化、マッピング、生成は決定論的に行われ、結果が報告されます。LLM はユーザーが確認するトークンリストの提案のみを行います。
• 誠実さと適切な確度 — 未入力／未マッピングのトークンと、ファイルの書き込み先をすべて明示します。
• ワークスペースの整理 — 出力は分かりやすいフォルダーに書き込みます。マスター、入力済みのソース、データは変更せずに保持します。extract_template は入力ファイルに上書きしません。

データの取り扱い

実行は完全にローカルです — テンプレートとデータはお使いのマシン上にとどまり、外部ツールに送信されることはないため、名前、金額、参照情報はその場で処理されます。いずれかの手順で外部サービスまたはサードパーティサービスにデータを送信する場合は、まず機微な個人データを匿名化し、データの外部送信についてユーザーの確認を得てください。このスキル自体にネットワーク接続や認証情報は必要ありません。

注意点

1. find のテキストは完全一致させてください — 句読点や通貨記号も含め、語句をそのままコピーしてください。生成前に not_found リストを確認します。
2. 可能な限り、トークン名を列ヘッダーと同じにします — そうすればマッピングが自動で行われます。それ以外の場合は token_to_column を渡してください。
3. 一括生成の前に確認する — テンプレートを一度修正するほうが、バッチ全体を再発行するよりも効率的です。
4. MISSING フラグを隠すべきエラーとして扱わない — 明示し、データ／マッピングを修正して再実行してください。
5. データテーブルは .xlsx フォームテンプレートとは別ファイルです — 2つを混同しないでください。

検証チェックリスト

• マスターを分析し、定型文と異なる箇所を特定した。または、入力済みの .docx に対して extract_template を実行し、マッピングを確認した。
• 生成前にトークンの一覧を提案し、ユーザーの確認を得た。
• tokenise の not_found 一覧が空である（または解決済み）。extract の uncertain が提示されている。
• トークンから列へのマッピングを確認し、デフォルト値を検証した。
• バッチを生成し、ファイル数と出力フォルダーを報告した。
• すべての «MISSING:…» と unmapped_tokens の項目をユーザーに提示した。

要件

• Python 3.8 以降
• pip install python-docx openpyxl
• ネットワークアクセスと認証情報は不要です。すべてローカルのファイル入出力で処理します。