email-designer

电子邮件设计器

通过对话生成兼容 Outlook 的电子邮件模板。用户描述想要的内容，你生成一个像素级精准的 EML 文件，可在 Outlook 中作为草稿打开。

工作原理

此技能分为三个层次：

1. 规则 — 生成 HTML 时遵循的 Outlook 兼容性约束
2. 模板 — 可供组合使用的预构建组件和布局
3. 代码块 — 用于生成 EML 文件的 Python 脚本

核心功能（HTML + EML）仅使用 Python 标准库。可选功能（图表、页眉横幅、图像优化）需要额外的软件包，在需要时会自动安装 — 请参阅步骤 0。

步骤 0：环境检查

开始之前，请确认 Python 3 可用。尝试运行以下命令（选择适用于当前平台的命令）：

python3 --version    # macOS / Linux
python --version     # Windows (check that output shows 3.x, not 2.x)

• 已安装且 Python 版本 ≥ 3.8 → 静默继续（不要向用户提及检查）。
• 未安装或版本过低 → 不要继续。请改为：
  1. 运行 uname -s 和 uname -m（Windows 上则运行 systeminfo），检测用户的操作系统和架构。
  2. 如果具备网页搜索能力，搜索在用户的平台上安装 Python 3 的最新推荐方式，并提供具体命令。
  3. 如果无法搜索，请以用户使用的语言显示以下消息：

     中文：Email Designer 需要 Python 3.8 或更高版本。请访问 https://www.python.org/downloads/ 下载并安装适合你操作系统的版本，安装完成后重新运行。

     English: Email Designer requires Python 3.8 or later. Please visit https://www.python.org/downloads/ to download and install the version for your OS, then try again.

  4. 在此处停止，等待用户安装完成后再继续。

可选依赖项（需要时自动安装）

如果步骤 1 确认电子邮件需要图表或图像处理：

1. 执行 code-blocks/deps-checker.py → check_and_install(features)
   • features 为 ['charts']、['images'] 或 ['charts', 'images']
2. 全部可用 → 静默继续
3. 刚刚安装完成 → 静默继续（安装过程不会显示信息）
4. 安装失败 → 告知用户并提供替代方案：
   • 图表不可用 →“我会改用 HTML 表格和统计网格组件”
   • 图像不可用 →“我会使用 HTML 页眉组件，并跳过压缩”

功能	软件包	支持的功能
charts	plotly, kaleido	生成柱状图、折线图、热力图、饼图
images	pillow	合成页眉横幅、压缩图像
excel	openpyxl	生成 Excel 模板并加载数据（生产模式）

模式检测

环境检查通过后，根据用户输入和现有项目确定合适的模式。这三种模式是：

1. 导入模式 — 如果用户提供了 .eml 文件（或提到导入／复刻现有邮件）：

1. 执行 code-blocks/eml-to-html.py → extract_from_eml(eml_path)，提取 HTML 和嵌入的图片
2. 执行 save_extracted(result, output_dir)，保存 HTML 和图片，并将 CID 引用转换为相对路径
3. 自动在浏览器中打开提取的 HTML 以供预览
4. 询问用户：“已提取邮件内容并预览。接下来您想： A) 在此基础上调整设计（进入设计模式 Step 3） B) 直接沉淀为可复用量产项目（进入沉淀流程）”
5. 如果选 A → 验证提取的 HTML（code-blocks/html-validator.py → validate(html)），通过 code-blocks/output-manager.py → create_project(name) 整理输出，然后跳转至 Step 3（预览和调整），以提取的 HTML 作为起点
6. 如果选 B → 阅读 rules/production-mode.md § "Crystallization Process"，并按步骤 C0-C5 执行

2. 量产模式 — 如果 email-projects/ 目录中存在已沉淀的项目：

1. 扫描同时包含 template.html 和 template.xlsx 的子目录
2. 如果存在项目，则列出这些项目：

   “检测到以下邮件模板项目：

   1. {project-name-1}
   2. {project-name-2} ... 请选择项目编号并提供 Excel 数据文件路径（如：1 /path/to/data.xlsx）， 或输入 'new' 创建新邮件。”

3. 如果用户选择某个项目 → 先运行 code-blocks/deps-checker.py → check_and_install(features=['excel'])，确保已安装 openpyxl， 然后阅读 rules/production-mode.md 并按步骤 P0-P4 执行
4. 如果用户输入 new → 继续使用设计模式

3. 设计模式 — 未提供 EML 文件且没有现有项目时的默认模式（或用户 选择了 new）。继续执行下方的 Step 1。

自适应流程

并非每个请求都需要完整向导。根据用户输入调整处理方式：

如果用户的请求已经包含足够的信息（布局、颜色、宽度、内容类型都能从上下文中明确），则跳过前面的步骤。例如，“帮我做一个蓝色的产品更新邮件 模板，600px”已经说明：单栏、蓝色（#2563eb）、600px。直接开始生成。

如果请求需要澄清，则使用下方的引导式交互收集所需信息。目标是让决策变得简单，尤其是对于可能不了解邮件设计术语的非技术用户。

引导式交互

电子邮件设计有 6 个决策维度。Agent 的任务是根据用户请求推断已有信息，然后询问其余内容——每次只问一个问题，并始终提供推荐的默认选项。

6 个维度（按此顺序询问——前面的回答会影响后续默认选项）：

#	维度	要决定的内容	处理方式
1	用途与布局	邮件类型 → 决定结构	通常可从请求中推断。进行确认，不要从头询问
2	内容模块	要包含哪些版块（KPI 卡片、图表、文章列表、表格……）	根据布局类型推荐一组默认内容。允许用户添加或移除
3	视觉风格	配色方案、设计基调	除非用户提到品牌或颜色，否则询问。提供 3-4 个有名称的预设
4	数据与素材	是否有数据文件？图片？Logo？是否需要图表？	可根据布局类型推断（仪表板需要数据）。询问确认
5	宽度	600 / 800 / 1200px	根据布局设置默认值（简报邮件→600，报告→800）。进行确认
6	内容	使用真实内容还是占位内容？	只有在尚不明确时才询问

交互原则：

重要——不要在一条消息中问多个问题。 每条消息必须只针对一个维度提问。一次列出所有问题会让用户不知所措，也违背引导式交互的目的。

❌ 不好（一次抛出所有问题）： “请告诉我：1. 报告内容范围 2. 视觉风格 3. 布局偏好 4. 邮件宽度 5. 其他”

✅ 好（每条消息只问一个问题，并提供推荐）： 消息 1：“季度商机报告——我推荐 Dashboard 布局（800px）。通常包含：A) KPI 指标卡 B) 趋势图表……” 消息 2：“配色风格？A) 深蓝商务 B)……” 消息 3：“你有现成的数据吗？A) 有 B) 先用示例数据”

• 先推断，再确认。 解析用户已经说过的所有内容。对于“商机季度报告邮件”，你已经知道：采用 Dashboard 布局，可能需要图表和 KPI 卡片，800px 比较合适。说明你的推断并询问确认——不要列出全部 7 种布局让用户选择。

• 每条消息只问一个问题。 每条消息只询问一个维度。这样能让用户专注，也更容易作答。如果某个维度已经明确（由你推断或用户说明），就完全跳过。

• 始终提供推荐。 每个问题都要附上标明的推荐选项和简短理由：“推荐 A（深蓝商务），适合正式的季度报告”。没有偏好的用户可以直接接受。

• 优先使用选择题。 使用带简短说明的 A/B/C/D 选项，而不是开放式问题。提供自定义选项（例如“D) 自定义颜色”）。

• 最多问 3 个问题。 如果问了 3 个问题后仍有未知项，其余内容采用合理的默认值。大多数用户在超过 3 轮后会失去耐心。仅当两个维度密切相关时才合并提问（例如布局 + 宽度）。

“帮我做一个商机季度报告邮件”的示例流程：

Agent 推断：Dashboard 布局、800px，需要图表/KPI。

问题 1（确认推断 + 询问模块）：

“季度商机报告——我推荐 Dashboard 布局（800px）。这类报告通常包含： A) KPI 指标卡 B) 趋势图表 C) 漏斗图 D) 分布图 E) Top 列表 F) 总结文字 推荐：全选，季度报告的信息量较大。你要哪些？”

问题 2（视觉风格）：

“配色风格？ A) 深蓝商务 B) 深绿增长 C) 紫色科技 D) 自定义颜色 推荐：A 深蓝商务，适合正式的季度报告”

问题 3（数据）：

“你有现成的数据吗？ A) 有，我提供数据 B) 先用示例数据，之后替换”

然后开始生成——不再提问。

第 1 步：了解需求

通过上述引导式交互，确定以下维度：

• 布局：查看 templates/layouts/ 了解可选项：

  • Single Column（单栏）——产品更新、公告、每周摘要
  • Two Column（双栏）——带有侧边栏数据的报告
  • Magazine（杂志）——带有主视觉图片和文章的编辑内容
  • Announcement（公告）——简洁、居中、带有行动号召
  • Dashboard（数据面板）——KPI 报告、分析摘要、每周回顾
  • Transactional（事务通知）——订单确认、密码重置、系统提醒
  • Onboarding（引导流程）——欢迎邮件、入门指南
  • Custom（自定义）——由用户描述，你使用组件进行设计

• 宽度：600px（移动优先）/ 800px（均衡）/ 1200px（桌面）/ 自定义

• 颜色：用户是否提供了品牌图片？如果提供，请分析图片中的颜色（使用视觉能力读取图片）。 否则，提供预设选项：蓝色 #2563eb、绿色 #059669、橙色 #ea580c、紫色 #7c3aed、灰色 #374151。 （完整调色板见 rules/brand-color-extraction.md）

• 已保存的模板：运行 code-blocks/template-manager.py → list_templates()，检查是否有可复用的模板。如果有，优先向用户提供。

素材评估

了解布局、宽度和颜色后，评估需要哪些视觉素材：

• 用户提供了数据（Excel、CSV、表格、对话中的数字）→ 规划图表生成（第 1.5a 步）
• 用户提供了背景图片 → 规划页眉横幅合成（第 1.5b 步）
• 用户提供了本地图片 → 规划图片优化（第 1.5c 步）
• 邮件类型为 Dashboard/每周报告/数据报告，但未提供数据 → 询问：“您有想要可视化为图表的数据吗？”

如果需要准备素材：

1. 运行依赖项检查（第 0 步，可选依赖项）
2. 继续执行第 1.5 步

如果不需要素材 → 直接跳到第 2 步。

第 1.5 步：素材准备（确定需要素材时）

生成 HTML 前准备好视觉资源。所有输出都保存到项目的 images/ 目录。

1.5a：图表生成（用户提供数据时）

1. 阅读 rules/chart-design-system.md，了解视觉限制
2. 分析数据结构 → 推荐图表类型：
   • 类别 × 单个数值 → 横向条形图
   • 类别 × 多个系列 → 堆叠条形图
   • 时间 × 数值 → 折线图
   • 二维矩阵 → 热力图
   • 整体的组成部分 → 饼图/环形图
   • ≤ 5 个数据点 → 建议改用 HTML 表格或统计网格
3. 与用户确认：“根据您的数据，我建议使用 [type] 图表。可以吗？”
4. 执行 code-blocks/chart-generator.py：

   gen = EmailChartGenerator(container_width=WIDTH, output_dir='OUTPUT/images')
   path = gen.bar_chart(categories=[...], series={...}, title='...', filename='chart_name.png')
   

5. 与用户预览图表图片，必要时进行迭代
6. 最终 PNG 文件位于 images/{chart_name}.png

1.5b：页眉横幅（用户提供背景图片时）

1. 执行 code-blocks/header-generator.py：

   gen = HeaderGenerator()
   path = gen.generate(title='...', subtitle='...', output_path='OUTPUT/images/header_banner.jpg',
                       bg_image='path/to/bg.png')  # or bg_color='#2563eb' for solid
   

2. 如果没有背景图片，但用户想要视觉横幅 → 提供纯色选项
3. 如果用户不想要横幅图片 → 改用 HTML 页眉组件（不需要 Pillow）
4. 输出：images/header_banner.jpg

1.5c：图片优化（用户提供本地图片时）

1. 确保图片位于项目的 images/ 目录
2. 检查文件名——非 ASCII 文件名必须改为 ASCII 名称（参见 rules/design-system.md § 图片文件名规则）
3. 执行 code-blocks/image-optimizer.py：

   results = optimize_directory('OUTPUT/images/', threshold_kb=200)
   # results = [(filename, original_kb, compressed_kb), ...]
   

4. 如果有文件经过优化，告知用户节省的空间

第 2 步：生成 HTML

生成 HTML 前，请阅读以下文件以获取指导：

• rules/outlook-compatibility.md — Outlook 兼容性规则（必读）
• rules/design-system.md — 通用设计基础（颜色、排版、间距） （这能让邮件看起来专业且现代，而不只是兼容）
• rules/design-system-data-report.md — 仅用于数据密集型邮件（KPI 仪表板、 周报、状态更新）。简单的新闻简报／公告无需阅读。
• rules/chart-design-system.md — 仅在生成图表时阅读。适用于嵌入邮件的图表的 配色系统、排版、尺寸和数据标签规范。
• rules/email-best-practices.md — 设计指南
• rules/style-presets.md — 设计风格预设（Corporate、Editorial、Minimal）。 选择符合邮件用途的风格，以指导间距、字号和颜色用法。
• rules/placeholder-i18n.md — 使用符合用户语言的占位符
• templates/components/*.html — 经过验证且兼容 Outlook 的组件模式 （包括适用于高级布局的 stats-grid、nav-bar、status-badge）
• examples/example-*.html — 可供参考的完整可用示例

设计提示——保持页眉紧凑：页眉应像导航栏，而不是主视觉横幅。将徽标和标题 放在同一行，总高度控制在 60-70px 左右。避免在页眉中加入过高的间隔行和过大的 徽标——将垂直空间留给内容。

Outlook 兼容性为何重要：Windows 上的 Outlook 2007-2019 使用 Microsoft Word 的渲染引擎，而不是浏览器引擎。这意味着大多数现代 CSS （flexbox、grid、border-radius、margin）都会被忽略或无法正常显示。规则文件包含 经过生产环境验证的模式，可正确处理这些问题。templates/components/ 中的每种 HTML 模式都已验证，确保能在 Outlook、Gmail、Apple Mail 和 Web 客户端中正确显示。

生成时的关键原则：

• 绝不要插入用户未要求的内容——不添加“由 AI 生成”的水印、 工具鸣谢或免责声明。页脚只能包含用户设计中指定的内容（版权信息、退订链接等）。
• 严格遵循 rules/outlook-compatibility.md——其中涵盖表格布局、内联 样式、VML 分隔线、间隔行、MSO 条件语句以及其他所有 Outlook 特殊问题。 生成任何 HTML 前，请先阅读该文件。
• Gmail 大小限制——HTML 不得超过 102KB，否则 Gmail 会截断邮件。
• 预览文本——在 <body> 后立即添加隐藏的 <div style="display:none;">Preview text</div>。

生成后：

1. 先验证：执行 code-blocks/html-validator.py → validate(html)。 检查 32 项规则，包括：禁止使用的 CSS、缺少 VML、列宽溢出、文本溢出、 Gmail 102KB 大小限制、缺少 alt 文本、非 HTTPS 链接、缺少预览文本、 元素超出容器宽度。继续之前，请修复所有错误。
2. 整理输出：执行 code-blocks/output-manager.py → create_project(name) 在用户的工作目录中创建带时间戳的目录 （例如 ./output/2026-03-15_product-report/）。绝不要将输出文件 写入技能自身的安装目录。
3. 将 HTML 保存到 {project_dir}/newsletter-preview.html

第 3 步：预览与调整

1. 自动在浏览器中打开：执行 code-blocks/preview-helper.py → open_in_browser()
   • 所有图像都会直接渲染（图表、页眉横幅、内容图像）
   • 预览无需生成 EML
2. 在对话中展示 ASCII 布局摘要：→ ascii_layout_summary(html)
3. 询问是否需要调整，并不断迭代，直到用户满意

第 4 步：填写内容（可选）

询问：“现在要填写内容，还是在 Outlook 中保留占位符以便稍后编辑？”

如果现在填写：

1. 执行 code-blocks/content-filler.py → generate_fill_template(html)，显示 所有占位符组成的类 YAML 模板，供用户一次性填写
2. 收集内容——可以逐项收集，也可以接收用户提供的批量字典
3. 执行 fill_batch(html, content_dict, image_dir)，高效批量填写 （自动将目录中的图片映射到 CID 占位符）
4. 重新预览，并检查 unfilled_placeholders(html)，查看是否还有未填写的占位符

快速编辑（第 2 步之后随时可用）

如果用户要求定向修改（例如“将页眉颜色改为红色”、 “放大标题”），请使用 code-blocks/html-patcher.py，而不是重新生成：

• replace_color(html, old, new) — 全局替换颜色
• change_width(html, old_w, new_w) — 调整容器宽度
• replace_text(html, old, new) — 修改可见文本
• add_section(html, section_html) — 在页脚前插入内容区块
• patch_file(path, colors={...}, texts={...}) — 一次应用多项补丁

应用补丁后重新验证：html-validator.py → validate(patched_html)。

第 5 步：生成 EML

这一步会将 HTML 转换为真正的邮件文件。有两种方式：

选项 A（推荐）：使用 eml-builder.py 流式 API

编写一段简短的 Python 脚本，使用 EMLBuilder 类：

from pathlib import Path
# Read the eml-builder.py source, then use:
eml = (
    EMLBuilder(sender="", subject="Newsletter Title")
    .set_html(Path("output/newsletter-preview.html").read_text())
    .add_image("logo", "output/images/logo.png")   # for each CID image
    .build("output/newsletter.eml")
)

选项 B：使用 html-to-eml.py 脚本模板

复制脚本，编辑顶部的 CONFIG 部分，然后运行：

HTML_FILE = "output/newsletter-preview.html"   # your generated HTML
OUTPUT_EML = "output/newsletter.eml"           # output path
SUBJECT = "..."                                # ask user
SENDER = ""                                    # optional
TO_ADDRS = []                                  # optional
IMAGE_DIR = "output/images"                    # if images exist

两种方式都使用 Python 内置的 email 模块——无需安装 pip。它们会创建 规范的 MIME 结构（multipart/alternative → text/plain + multipart/related → text/html + CID 图片），并设置 X-Unsent: 1，使 Outlook 以草稿/撰写模式打开邮件。

重要——只能使用提供的脚本。 生成 EML 时，必须使用 eml-builder.py（选项 A）或 html-to-eml.py（选项 B）。 不要自行编写临时或内联 Python 脚本来生成 EML——这很可能导致 MIME 结构不正确，或遗漏 CID 图片嵌入，从而造成图片在 Outlook 中无法正常显示。

生成 EML 后，继续操作前必须先验证：

1. 执行 code-blocks/eml-validator.py → validate_eml(eml_path)。 此工具会检查 14 条规则，包括：MIME 结构、text/plain 回退内容、CID 转发 完整性（每个 src="cid:xxx" 都有对应的嵌入图片）、残留的未解析图片路径、 Content-ID 格式（RFC 2392）、X-Unsent 标头、Content-Disposition inline，以及文件大小。 检查会根据情况调整——仅当 HTML 实际引用图片时，才会触发图片相关规则；纯文本邮件 可顺利通过检查。
2. 继续第 6 步之前，修复所有错误。

验证通过后，必须继续执行第 6 步——不要在此处结束对话。

第 6 步：收尾

请始终按以下顺序完成所有操作：

6a. 提议将模板沉淀为可重复使用的项目

这很重要——许多用户将来会希望使用不同的数据重复利用此模板 （例如，周报、定期通讯）。务必询问：

“邮件设计完成。是否要将此模板沉淀为可复用项目？以后只需填 Excel 即可重复生成。”

如果用户同意，请阅读 rules/production-mode.md §“沉淀流程”，并按步骤 C0-C5 操作。 沉淀完成后，继续执行下方的 6b 和 6c。 如果用户拒绝，也继续执行 6b 和 6c。

6b. 保存模板并显示输出

1. 提议保存模板：执行 code-blocks/template-manager.py → save_template()
2. 使用绝对路径（而非仅文件名）显示输出文件的位置，以便用户轻松找到并打开文件。 例如：

   EML 文件:  /Users/name/project/output/2026-03-15_report/newsletter.eml
   HTML 预览: /Users/name/project/output/2026-03-15_report/newsletter-preview.html
   图片目录:  /Users/name/project/output/2026-03-15_report/images/
   

   使用实际的工作目录路径，不要使用 output/... 之类的相对路径。

6c. 显示使用指南

显示相应的 Outlook 使用指南：

• 中文用户 → templates/guides/outlook-usage-guide-zh.md
• 英文用户 → templates/guides/outlook-usage-guide-en.md

占位符系统

此技能使用两种不同的占位符机制，用于不同目的：

• {{placeholder}}（设计模式）——由 code-blocks/content-filler.py 用于交互式设计期间的一次性占位符填充。进行简单的字符串替换。在设计模式下从头创建电子邮件时使用此机制。

• `` comments（生产模式）——在定型后的 template.html 文件中用作结构标记，供 AI Agent 读取，以了解应在何处插入 Excel 数据。这些标记不会由 content-filler.py 处理。 详情请参阅 rules/production-mode.md。

这两种系统服务于不同的工作流，互不影响。content-filler.py 是设计模式工具；生产模式使用 AI Agent 作为渲染引擎。

文件映射

rules/
  outlook-compatibility.md   ← Read before generating HTML (Outlook rendering rules)
  design-system.md           ← Universal: colors, typography, spacing (ALWAYS read)
  design-system-data-report.md ← Extension: KPI cards, status badges, trends (data emails only)
  email-best-practices.md    ← Design guidance (widths, colors, typography)
  style-presets.md           ← 3 design styles: Corporate, Editorial, Minimal
  placeholder-i18n.md        ← Localized placeholder text (zh/en/ja)
  chart-design-system.md     ← Chart colors, typography, sizing (read before chart generation)
  brand-color-extraction.md  ← Color extraction + preset palettes
  production-mode.md         ← Production mode: detection, workflow, crystallization, Excel integration

templates/
  components/*.html          ← 19 Outlook-safe HTML building blocks
                                (header, section, card, table, image-placeholder,
                                 divider, footer, stats-grid, nav-bar, status-badge,
                                 progress-bar, button, callout, testimonial,
                                 feature-list, pricing-table, team-member,
                                 alert, timeline)
  layouts/*.md               ← 7 preset layout descriptions
                                (single-column, two-column, magazine, announcement,
                                 dashboard, transactional, onboarding)
  guides/*.md                ← End-user Outlook usage guides (zh/en)

code-blocks/
  html-validator.py          ← Run AFTER generating HTML, BEFORE EML (auto-check 32 rules)
  eml-validator.py           ← Run AFTER generating EML, BEFORE Step 6 (auto-check 14 rules)
  html-patcher.py            ← Targeted edits (color, width, text) without regenerating
  output-manager.py          ← Timestamped project directories for organized output
  eml-builder.py             ← EML builder class (fluent API)
  cid-embedder.py            ← Image scanning + placeholder PNG creation
  html-to-eml.py             ← HTML→EML conversion (edit CONFIG section, then execute)
  eml-to-html.py             ← Extract HTML + images from .eml files (Import Mode)
  content-filler.py          ← {{placeholder}} replacement + batch filling
  template-manager.py        ← Save/load/list custom templates
  preview-helper.py          ← Browser auto-open + ASCII layout
  deps-checker.py            ← Auto-install optional dependencies (charts, images)
  chart-generator.py         ← Plotly chart generation (bar, line, heatmap, pie)
  header-generator.py        ← Header banner image compositing (text on background)
  image-optimizer.py         ← Image compression (PNG→JPEG, resize, optimize)
  excel-template-generator.py ← Generate & load Excel data templates (openpyxl)

examples/
  example-single-column.html ← Complete 600px single-column reference
  example-two-column.html    ← Complete 800px two-column reference