converting-email-templates

转换邮件模板

目的

自动将其他邮件服务提供商的邮件模板转换为 Mailtrap 兼容的 Handlebars 语法。既支持确定性模式转换（通过 Python 脚本），也能借助 LLM 智能处理复杂边缘情况。

相关技能： using-email-templates（Handlebars 语法、通过 API 发送模板）、sending-emails（流基础和身份验证）、authorizing-api-requests（令牌、环境变量、account_id 解析——转换后创建模板或通过 Templates API 发送邮件时需要）。

输入

• 源服务提供商（必填）：sendgrid、mailgun、mandrill-handlebars、mandrill-mergetags、postmark、brevo 或 ses
• 输入：单个模板文件路径、包含 .html 模板文件的目录，或直接粘贴的原始 HTML
• 输出目录（可选）：默认为输入文件旁的 /converted/ 子目录

如果用户未指定源服务提供商，请先询问再继续。如果用户直接在聊天中粘贴模板 HTML，请先将其保存到临时 .html 文件。

工作流

步骤 1：检测模式

快速模式（默认）：适用于具有确定性转换模式的服务提供商。Python 脚本可以可靠地处理这些转换。

深度模式：在以下情况下触发：

• 服务提供商为 brevo，且模板包含嵌套循环、多个筛选器或复杂的条件嵌套
• 脚本标记了可能需要 LLM 判断的模式
• 用户明确请求深度模式
• 提供了内联 HTML（直接通过 LLM 转换）

步骤 2：运行转换器脚本

运行 Python 转换器脚本：

python3 {skill_dir}/scripts/converter.py \
  --provider {provider} \
  --input {input_path} \
  --output {output_dir}

其中 {skill_dir} 是包含此 SKILL.md 文件的目录。

读取输出：

• 退出代码为 0：转换成功，未发现标记项。继续执行步骤 4。
• 退出代码为 1：转换已完成，但有标记项。继续执行步骤 3。
• 退出代码为 2：发生错误。向用户报告并停止。

读取每个转换后模板旁生成的 .report.txt 文件。批量转换时，也要读取 _summary.txt。

注意： 存在标记项时，脚本会自动：

• 在转换后文件的开头添加 `` 注释
• 将不支持的语法放入 `` HTML 注释中，这样就可以将文件粘贴到 Mailtrap 编辑器中，而不会触发解析器错误

步骤 3：处理标记项（深度模式）

对于报告中的每个标记项：

1. 查看原始模板中被标记的行。
2. 查阅 references/conversion-rules.md 中的具体规则和建议操作。
3. 对标记项分类：
   • 需要修改应用层（例如 formatDate、比较辅助函数）：无法在模板中解决。向用户清楚说明需要在应用代码中进行哪些修改，并建议替换后的变量名称。
   • 可在模板层修复（例如 Brevo 嵌套循环、Mandrill mc:edit 区域）：根据 LLM 判断进行转换。向用户展示转换前后内容，并在写入前征求确认。
   • 有歧义（例如 Postmark 闭合标签不匹配）：向用户展示原始上下文和转换结果，并请用户核对。

按类别对标记项分组展示：

## Conversion Complete

### Auto-converted: [count] changes
[Brief summary or collapsed details]

### Needs your application code: [count] flags
[For each: what to change, why, suggested variable name]

### Needs verification: [count] flags
[For each: show before/after, ask for confirmation]

步骤 4：展示结果

单个文件：

Converted: {filename}
Changes: [count] | Flags: [count]
Output: {output_path}

[Show the conversion report summary]
[If flags exist, show the categorized flag breakdown from Step 3]

批量转换：

Converted: [count] files
Total changes: [count] | Total flags: [count]
Clean: [count] files | Needs review: [count] files
Output: {output_dir}

[Show the summary report]
[List files needing review with their specific flags]

第 5 步：API 字段映射提醒

模板转换后，始终提醒用户需要进行哪些 API 端更改。请参阅快速映射表：

提供商	旧模板字段	旧变量字段	Mailtrap 字段	Mailtrap 变量
SendGrid	template_id	personalizations[].dynamic_template_data	template_uuid	template_variables
Mailgun	template	t:variables	template_uuid	template_variables
Mandrill	template_name	global_merge_vars + merge_vars	template_uuid	template_variables
Postmark	TemplateId/TemplateAlias	TemplateModel	template_uuid	template_variables
Brevo	templateId	params	template_uuid	template_variables
Amazon SES	TemplateName/TemplateArn	TemplateData	template_uuid	template_variables

只显示刚刚转换的提供商对应的行。

行内转换（无文件）

如果用户直接在聊天中粘贴模板 HTML，而不是提供文件路径：

1. 识别源提供商（如果用户未说明，请询问）。
2. 使用 LLM 智能，直接应用 references/conversion-rules.md 中的转换规则。
3. 在转换后的输出中，将不支持的语法用 `` HTML 注释括起来（与脚本使用的格式相同）。这样可以避免用户将输出粘贴到 Mailtrap 时编辑器报错。
4. 如果存在标记项，请在转换后输出的顶部添加 `` 注释，注明需要解决的标记模式数量。
5. 展示转换后的 Handlebars 输出，并列出所做的更改。
6. 标记需要在应用层处理的模式。
7. 提供将结果保存到文件的选项。

此模式始终使用 Deep 模式（LLM），因为没有文件可传递给脚本。

规则

• 绝不静默跳过已标记的模式。 必须向用户报告每个标记项。
• 绝不修改原始文件。 转换后的输出始终写入输出目录。
• 保留 HTML 结构。 只修改模板语法（变量、条件、循环、辅助函数）。不要改动 HTML 标签、属性、CSS 或非模板内容。
• 如有疑问，标记出来。 如果某个模式存在歧义，应将其标记为需要人工审核，而不是进行可能错误的转换。
• 报告数量。 始终显示更改项和标记项的数量，让用户了解处理范围。
• 一次处理一个提供商。 如果目录中包含多个提供商的模板，请让用户先将它们分开，或指定本批次要处理的提供商。