converting-email-templates

用途

该技能用于将其他邮件服务商（SendGrid、Mailgun、Mandrill、Postmark、Brevo、Amazon SES）的邮件模板自动转换为 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。

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

• 在转换文件顶部添加 <!-- WARNING: ... --> 注释
• 将不支持的语法包裹在 <!-- FLAGGED [RULE]: message --> 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. 将不支持的语法包裹在 <!-- FLAGGED [RULE]: message --> HTML 注释中（与脚本格式相同）。这防止用户将输出粘贴到 Mailtrap 时出现编辑器错误。
4. 如果有标记，在转换输出顶部添加 <!-- WARNING: ... --> 注释，说明有多少标记模式需要解决。
5. 呈现转换后的 Handlebars 输出及所做更改列表。
6. 标记任何需要应用层更改的模式。
7. 提供将结果保存到文件的选项。

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

规则

• 绝不静默跳过标记模式。每个标记都必须报告给用户。
• 绝不修改原始文件。转换输出始终进入输出目录。
• 保留 HTML 结构。仅修改模板语法（变量、条件、循环、助手）。不触碰 HTML 标签、属性、CSS 或非模板内容。
• 有疑问时标记。如果模式模糊，标记以供手动审查，而不是进行错误转换。
• 报告计数。始终显示更改和标记的数量，以便用户了解范围。
• 一次一个服务商。如果目录包含来自多个服务商的模板，请用户分开或指定批次的提供商。