当需要批量生成个性化 Word/Excel 等文档时…

适用于把同一份模板套用到多行数据，生成合同、信件、报告、证书或表单等文档。

适用场景

解决思路

1. 定义模板：在 Word、Excel、PowerPoint 等文档中用占位符标记待填字段，再用数据自动替换或渲染，适用于邮件合并、批量信件/合同、个性化报告、证书、表单自动填写。
2. 使用 Jinja2 风格模板语法：`{{ variable }}` 做简单替换；`{% for item in list %}` 做循环；`{% if condition %}` 做条件；`{{ date | format_date }}` 做过滤器。
3. Word 模板填充：用 `docxtpl.DocxTemplate` 读取带占位符的模板；实现 `fill_template(template_path: str, data: dict, output_path: str)`，内部执行 `doc = DocxTemplate(template_path)`、`doc.render(data)`、`doc.save(output_path)`，并返回 `output_path`。
4. Word 填充调用示例：传入数据字典，如 `{'name': 'John Smith', 'order_id': 'ORD-12345', 'items': [{'name': 'Product A', 'qty': 2, 'price': 29.99}, {'name': 'Product B', 'qty': 1, 'price': 49.99}], 'total': 109.97}`，输出到 `output/confirmation_john.docx`。
5. Excel 模板填充：用 `openpyxl.load_workbook` 打开模板并取 `wb.active`；遍历 `ws.iter_rows()` 的每个单元格；若单元格值为字符串，对 `data` 中每个键值构造占位符 `'{{' + key + '}}'`，若占位符在单元格值中则用 `str(value)` 替换；最后 `wb.save(output_path)` 并返回。
6. 批量生成/邮件合并：用 `csv` 读取数据 CSV，用 `pathlib.Path(output_dir).mkdir(exist_ok=True)` 创建输出目录；用 `csv.DictReader` 逐行读取；对第 i 行生成 `f'{output_dir}/document_{i+1}.docx'`；调用 `fill_template(template_path, row, output_path)`；打印已生成文件。
7. 批量生成调用示例：`contacts.csv` 含 `name,email,company`；调用 `mail_merge('templates/welcome_letter.docx', 'data/contacts.csv', 'output/letters')`。
8. 高级条件内容：在模板中写 `{% if vip %} Thank you for being a VIP member! {% else %} Thank you for your purchase. {% endif %}`；用 `DocxTemplate('template.docx').render({'name': 'John', 'vip': True, 'discount': 20})` 后 `doc.save('output.docx')`。
9. 最佳实践：使用清晰占位符命名，如 `{{client_name}}`；渲染前校验数据；优雅处理缺失数据；将模板纳入版本控制。
10. 安装依赖：`pip install python-docx openpyxl python-pptx reportlab jinja2`；Word 部分示例使用 `docxtpl`，需确保已安装该库。
11. 使用流程：描述要完成的任务；提供所需的输入数据或文件；由执行者调用相应模板填充或批量生成操作。
12. 若使用 office-mcp，可调用 `fill_docx_template` 工具填充 Word 模板。

适用边界 · 注意事项

• 需要复杂排版、图表、宏或公式联动时，纯占位符替换可能不足以保留或生成正确效果。
• 数据未校验或大量缺失时，直接批量渲染可能生成错误文档。
• 未安装所需依赖、没有模板文件或没有输入数据时无法执行。