fill-template

填充模板（邮件合并）

将一个主模板和一个数据表转换为多份已填充的副本——每行生成一份，只替换变化的部分，并保留主模板的布局和样式。仅用于生成文档：不会发送、发布或签署任何内容。

适用范围与路由

当用户有一个模板和一个列表，并希望每行生成一份已填充的副本时，使用此技能；或者当用户提供了已填写的示例 .docx，并希望据此创建可复用的标记模板（extract_template）时，也使用此技能。不要用它来制作单封定制信件（只需编辑一份文档），也不要用于宿主环境要求采用其他文档处理流程的情况。本轮暂不支持从 .xlsx 表单提取模板。

用户提供的输入

1. 主模板——.docx 信函或表单，或 .xlsx 表单。每次运行使用一个主模板。 这是布局和样式的唯一依据。
2. 数据表——.xlsx 或 .csv 文件，每行对应一份输出，并包含标题行。列提供需要变化的值（姓名、金额、日期、参考编号等）。
3. （可选）命名模式——每个输出文件的命名方式，例如 Letter_{Name}。默认使用 <template>_<row-number>。

工作流（按顺序执行）

如果用户提供的是已填写的示例而不是母版，请先运行 extract（步骤 0），展示 ext["mapping"]，并等待确认后再生成。否则从步骤 1 开始。

0. 从已填写的 .docx 中提取（可选的反向流程）。 extract_template(src, out_dir, name=None) 会写入 <name>_tokenised.docx 和 <name>_data.csv （name 默认为源文件的名称，不含扩展名），并返回一份报告。变化的值会使用与 tokenise 相同的、感知运行的替换方式变为 {{Token}}。CSV 每个重复实例占一行。展示 report["mapping"]（字面值 → 令牌 → 位置）和所有 report["uncertain"] 条目——这些片段会保留为字面文本，而不会靠猜测处理。令牌名称仅来自五种带类型的形式： 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) 计数——这表示 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. 每行生成一个文件。

   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，以及每个文件中缺失的令牌。

6. 如实汇报。 告知用户生成了多少个文件以及文件所在位置，并指出所有 missing 标记和 unmapped_tokens 条目，以便在使用这批文件之前处理空缺内容。 输出均为草稿，发送前应由人工审核。

令牌化和替换的工作方式

• 令牌语法为 {{TokenName}}（花括号内的空格会被忽略）。
• .docx — 替换按文本运行处理：值会写入令牌开头所在的文本运行（继承其格式），令牌跨越的其他文本运行会被删减；令牌之外的文本运行保持原样。正文、表格（包括嵌套表格）以及页眉／页脚文本均会处理。
• .xlsx — 会替换任何工作表中任意单元格内的令牌；所有其他单元格内容、公式和格式都会保留（使用 openpyxl）。将令牌放在需要显示值的位置，例如单元格 B5 = {{Name}}。
• 数据中的日期默认显示为 DD MMM YYYY；整数会去掉末尾的 .0。对于货币或特定数字格式，请在数据文件中设置列格式——辅助程序会按原样插入值。
• 绝不杜撰。 如果某一行没有令牌对应的值，会写入 «MISSING: Token» 并记录在报告中。请修正数据（或映射）后重新运行；不要手动把空白改成杜撰的值。

安全

• 仅处理文件。 生成文档；绝不发送、发布、发邮件、签署或提交任何内容。
• 每次运行使用一个主模板。 不要在同一批处理中混用不同模板。
• 与主模板保持一致。 保留所提供模板的版式和样式；仅替换令牌。
• 批量生成前先确认。 生成批次前，须明确确认令牌化模板和映射。
• 显示所有空缺。 报告全部 «MISSING:…» 标记和未映射的令牌；绝不掩盖这些问题。

文件

• scripts/fill_template.py — 引擎：extract_template（已填写的 .docx → 模板 + 骨架）· read_content（分析）· tokenise / tokens_in · load_rows（.xlsx/.csv）· generate（每行一个 文件 + 报告）。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 表单模板是两个独立文件 — 不要混淆二者。

验证清单

• 已分析主模板；已识别与固定内容不同的可变部分。或者，已对一份已填写的 .docx 文件运行 extract_template 并确认映射。
• 已提出令牌列表，并在生成前由用户确认。
• tokenise 返回的 not_found 列表为空（或已解决）。已向用户展示 extract 返回的 uncertain 项。
• 已检查令牌→列的映射；已验证默认值。
• 已生成批次；已报告文件数量和输出文件夹。
• 已向用户展示每个 «MISSING:…» 和 unmapped_tokens 条目。

要求

• Python 3.8+
• pip install python-docx openpyxl
• 无网络访问权限，也无需凭据——所有文件 I/O 均在本地完成。