email-generation

邮件生成（渲染器）

使用固定模板集（email-prompt-building 中的 sequence.md）和 {{input_fields}} 已填充的联系人 CSV 渲染一组邮件。此技能是机械性的：选择变体、替换占位符、渲染为目标格式，并写入输出 CSV。

这里不会调用大模型。 所有策略推理都已在设计阶段完成（email-prompt-building）；所有逐行处理都已在上游的规范化和信息补充环节完成，并填入了输入字段。如果邮件有误，问题出在模板或输入数据——修正源数据后重新渲染。

架构原则

此技能是渲染器，不负责推理，也不负责执行。

template set (sequence.md) ─┐
                            ├──▶ route variant ─▶ substitute ─▶ render to target ──▶ emails CSV
contact CSV (fields filled) ┘

所需输入

输入	来源	必需
模板集	email-prompt-building 中的营销活动序列文件	是
联系人 CSV	输入字段已由规范化和信息补充环节填充	是

联系人 CSV 必须包含模板输入字段约定中的所有字段，以及路由键。如果某行缺少已声明字段，则应用该字段声明的回退值；如果无法挽救该行，则丢弃并报告。

渲染约定

此流水线实际出错的环节就在渲染。「替换占位符」掩盖了难点——换行和转义。此约定必须遵守。

换行模型

模板使用两种换行类型，渲染器必须保留二者的区别：

• \n\n（空行） = 段落分隔
• \n（单个） = 段落内的软换行（有意使用）

渲染目标——一个正文，三种输出

目标	换行处理	转义
review（emails.md / CSV 的 body 列）	保留 \n\n 和 \n 字面形式	无，但 CSV 写入器必须为包含多行内容的单元格加引号
html（Instantly / 序列工具）	\n → <br />（因此 \n\n → <br /><br />）	对内容中的 & < > 进行 HTML 转义
plain（纯文本渠道）	保留字面形式	无

操作顺序——不可更改

1. 选择路由变体——使用路由键（例如 customer_segment）选择触达变体。
2. 将 {{fields}} 替换到纯文本正文中。
3. 对完整拼接后的字符串进行转义和换行转换，且必须放在最后。

为何要按此顺序操作：如果在替换之前对模板进行 HTML 转义，那么像 Johnson & Johnson 这样的字段值就会未经转义地插入，从而破坏 HTML。对最终拼接后的字符串进行转义，才能同时涵盖模板文本和替换后的值。

参考渲染器

import html

def render(body: str, target: str) -> str:
    """body: assembled plain-text (variant chosen, {{fields}} substituted).
    target: 'review' | 'html' | 'plain'."""
    if target in ("review", "plain"):
        return body
    if target == "html":
        # escape content per line, THEN join with <br /> — never escape the tags
        return "<br />".join(html.escape(line) for line in body.split("\n"))
    raise ValueError(target)

渲染器必须防范的故障模式

• 第一大错误——忘记将 \n 转换为 <br>：邮件会变成一大块文字。所有 HTML 序列工具都需要进行此转换。
• 在替换之前转义——字段值中的 & < > 会破坏 HTML。
• 重复转义——会产生 &。只在最后一步转义一次。
• 未加引号的多行 CSV 单元格——body 列中的嵌入换行会导致行列错位。请使用真正的 CSV 写入器。
• 未替换的占位符——写入之前，渲染器必须断言任何输出中都不含 {{。残留的 {{company_name}} 表示字段未传入（例如，Touch 3 未收到 company_name）。

工作流

第 1 步：验证输入

• 读取模板集；收集所有 {{field}} 和路由键。
• 读取联系人 CSV 标题行；确认所有已声明的输入字段和路由键都存在。
• 报告任何不匹配，并在渲染前停止。

第 2 步：逐行渲染

对于每个联系人、每次触达：

1. 选择路由变体（如果该次触达有变体）。
2. 将输入字段替换到纯文本正文中；当字段值为空时，应用逐字段回退值。
3. 渲染为每种所需目标格式（review、html）。
4. 断言不含 {{。

主题行：仅首次触达包含主题；后续邮件的主题为空（延续同一邮件线程）。

第 3 步：写入输出

• 邮件 CSV — 每个（联系人 × 触达）一行：email, first_name, company_name, touch, variant, subject, body, body_html, gaps。gaps 列记录哪些字段使用了回退值（例如 industry=fallback）。
• 人工可读的审核文件 — 每封邮件单独一节。

将这两个文件写入 GTM 项目的 campaign-assets 位置。请参阅 references/render_emails.py 中的参考渲染器。

第 4 步：质量检查

• 所有行中均无未替换的 {{
• 变体路由正确 — 每个变体抽查一行
• \n\n 和 \n 在 HTML 目标中均保留为 <br /><br /> / <br />
• 包含 & / < 的字段值经过转义（不是原样输出，也没有重复转义）
• 行数 = 联系人数 × 触达次数；发生回退时已填充 gaps
• 后续触达的主题为空

反馈循环

当用户指出某封邮件有问题时：

1. 判断问题属于文案（→ 通过 email-prompt-building 修复模板）还是数据（→ 修复规范化/增强流程，确保输入字段正确）。
2. 重新渲染。切勿手动编辑单封邮件 — 修复始终针对模板或输入数据。

抑制名单

写入输出 CSV 前，剔除邮箱位于 GTM 项目抑制名单中的联系人（退订、退信、停用地址）。该名单的位置由项目决定；此技能只负责遵守名单。

还没有模板？

如果该活动没有 sequence.md，请使用 email-prompt-building 技能来设计模板。不要在此技能中临时编写文案 — 此技能只负责渲染。