juice-email-cli 2.1.6 → 2.1.8

package/README.md

@@ -1,18 +1,21 @@
 # juice-email-cli
 
-> 一个用于生成符合各大邮件平台标准的 HTML 邮件命令行工具，基于 [juice](https://github.com/Automattic/juice) 实现 CSS 内联，支持 Mustache 模板变量替换，同时输出标准版与压缩版两份文件。
+> 一个用于生成符合各大邮件平台标准的 HTML 邮件命令行工具，基于 [juice](https://github.com/Automattic/juice) 实现 CSS 内联，支持 Mustache 模板变量替换，同时输出标准版与压缩版。
 
 ---
 
 ## 功能特性
 
-- ✅ **CSS 内联** —— 将 `<style>` 中的样式全部内联为 `style=""` 属性，兼容 Gmail / Outlook / Apple Mail 等
-- ✅ **Mustache 模板变量** —— 支持 `{{变量名}}` 语法，通过配置文件批量替换
-- ✅ **Mustache 列表循环** —— 支持 `{{#items}}...{{/items}}` 遍历数组，支持嵌套循环
-- ✅ **三层配置合并** —— CLI 默认 < 用户目录 < 优先配置，三者层层合并
-- ✅ **双文件输出** —— 同时生成标准版 `.output.html` 和压缩版 `.minified.html`
-- ✅ **响应式保留** —— `@media`、`@font-face`、`@keyframes` 均不丢失
-- ✅ **Windows 右键菜单（自定义图标）** —— 子菜单层级，一键注册/卸载，支持自定义图标
+- **CSS 内联** —— 将 `<style>` 中的样式全部内联为 `style=""` 属性，兼容 Gmail / Outlook / Apple Mail 等
+- **Mustache 模板变量** —— 支持 `{{变量名}}` 语法，通过配置文件批量替换
+- **Mustache 列表循环** —— 支持 `{{#items}}...{{/items}}` 遍历数组，支持嵌套循环
+- **片段组装** —— 将片段 HTML 插入模板的 `<tbody id="content">`，自动调整缩进，输出 4 个阶段文件
+- **三层配置合并** —— CLI 默认 < 用户目录 < 优先配置，层层合并
+- **HTML 标签渲染** —— 变量值中的 `<sup>`、`<sub>` 等 HTML 标签直接渲染（可通过 `rawHtml` 关闭）
+- **双文件输出** —— 普通模式生成 `.output.html` + `.minified.html`
+- **四文件输出** —— 片段模式生成 `.raw.html` + `.html` + `.output.html` + `.minified.html`
+- **交互模式** —— 无参数运行，逐步选择品牌、模板、片段、配置
+- **Windows 右键菜单** —— 子菜单层级，一键注册/卸载
 
 ---
 
@@ -42,32 +45,79 @@ npm link          # 链接到全局
 
 ## 使用方法
 
+### 普通模式（CSS 内联 + 压缩，输出 2 个文件）
+
 ```bash
-# 最简用法（自动查找配置文件）
+# 最简用法
 juice -f my-email.html
 
 # 指定配置文件
 juice -c project.yaml -f my-email.html
+
+# 使用 EDM 模板库中的模板
+juice -f edm/elabscience/elabscience-template.html
+```
+
+生成文件（与输入文件同目录）：
+
+| 文件 | 说明 |
+|------|------|
+| `<name>.output.html` | CSS 内联 + 变量替换后的标准版 |
+| `<name>.minified.html` | 压缩版 |
+
+### 片段模式（片段 + 模板拼接，输出 4 个文件）
+
+```bash
+# 完整指定片段和模板
+juice -s edm/elabscience/literature/snippet.html -f edm/elabscience/elabscience-template.html
+
+# 只指定片段，交互式选择模板
+juice -s edm/elabscience/literature/snippet.html
+
+# 自定义输出文件名
+juice -s snippet.html -f template.html -n my-output
 ```
 
-生成两个文件（与输入文件同目录）：
+生成文件（当前工作目录）：
 
 | 文件 | 说明 |
 |------|------|
-| `my-email.output.html` | CSS 内联 + 变量替换标准版 |
-| `my-email.minified.html` | 在标准版基础上压缩的精简版 |
+| `<name>.raw.html` | 原始组装（Mustache 未渲染，无 CSS 内联） |
+| `<name>.html` | 已渲染（Mustache 变量已替换，无 CSS 内联） |
+| `<name>.output.html` | Juice CSS 内联后 |
+| `<name>.minified.html` | 压缩版 |
+
+输出文件名默认为模板文件名（不含扩展名）。如果文件冲突，交互模式下可选择覆盖、自动版本号（`-v1`、`-v2`...）或重新输入。
+
+### 交互模式（逐步选择）
+
+```bash
+juice
+```
+
+流程：选择品牌 → 模板 → 片段文件夹 → 片段 HTML → 配置文件 → 输出文件名 → 确认执行。
 
 ### 参数说明
 
 | 参数 | 简写 | 说明 |
 |------|------|------|
-| `--file <path>` | `-f` | 输入 HTML 模板文件路径（必填） |
-| `--config <path>` | `-c` | 配置文件路径，不指定时自动查找输入文件同级目录 |
+| `--file <path>` | `-f` | 输入 HTML 模板文件路径 |
+| `--snippet <path>` | `-s` | 片段 HTML 文件路径：插入到模板 `<tbody id="content">` |
+| `--config <path>` | `-c` | 配置文件路径，不指定时自动查找 |
+| `--name <name>` | `-n` | 片段模式输出文件名（不含扩展名） |
 | `--install` | | 注册 Windows 右键菜单（需管理员权限） |
 | `--uninstall` | | 取消 Windows 右键菜单注册（需管理员权限） |
 | `--version` | `-v` | 查看版本号 |
 | `--help` | `-h` | 查看帮助 |
 
+### CLI 执行模式
+
+| `-s` | `-f` | `-c` | 执行模式 |
+|------|------|------|----------|
+| ✓ | * | * | 片段模式（-s 指定片段，-f 可选指定模板） |
+| ✗ | ✓ | * | 普通模式（生成 .output.html + .minified.html） |
+| ✗ | ✗ | * | 交互式片段模式（逐步选择） |
+
 ---
 
 ## 配置文件优先级
@@ -97,11 +147,17 @@ juice -c project.yaml -f my-email.html
 juice -c project.yaml -f email.html
 
 # 使用输入文件同级目录配置（与用户目录合并）
-# → email.html 同目录下有 juice.yaml
 juice -f email.html
+```
+
+### 片段模式配置
+
+片段模式下，会自动检测片段目录下的 `juice.yaml` / `juice.yml` 作为项目配置参与合并：
 
-# 无优先配置时，仅使用用户目录配置
-juice -f email.html
+```
+优先级 低 ──────────────────────────────────────────────────────── 高
+
+  内置默认  <  ~/juice.yaml  <  片段目录 juice.yaml  <  -c 指定
 ```
 
 ---
@@ -111,6 +167,9 @@ juice -f email.html
 用户配置文件（`~/juice.yaml` 或项目目录 `juice.yaml`）只需填写需要覆盖的字段，其余自动继承：
 
 ```yaml
+# 设为 false 时，变量值中的 HTML 标签会被转义
+rawHtml: true
+
 variables:
   brandName: "我的品牌"
   brandColor: "#ff6600"
@@ -127,28 +186,17 @@ variables:
       tag: "热销"
     - name: "产品 B"
       price: "¥199.00"
-    - name: "产品 C"
-      price: "¥299.00"
-
-  features:
-    - title: "特性一"
-      items:
-        - "优势 A"
-        - "优势 B"
-    - title: "特性二"
-      items:
-        - "优势 C"
-        - "优势 D"
+
+  # 变量值支持 HTML 标签（rawHtml: true 时）
+  overview:
+    title: "CD38-NAD<sup>+</sup> Axis Study"
+    keywords: "Immune Thrombocytopenia, NMN, NAD<sup>+</sup>"
 
 # juice 选项（全部可选，均有内置默认值）
 # juice:
 #   removeStyleTags: true
 #   preserveMediaQueries: true
-#   preservePseudos: true           # 保留 hover 等伪类
-#   preservedSelectors:             # 保留的选择器（不会被内联）
-#     - "a:hover"
-#   extraCssFiles:
-#     - email-reset.css
+#   preservePseudos: true
 
 # 输出后缀（可选）
 # output:
@@ -169,12 +217,26 @@ variables:
 <a href="{{ctaUrl}}" style="background-color: {{brandColor}};">{{ctaText}}</a>
 ```
 
+### HTML 标签在变量中
+
+当 `rawHtml: true`（默认）时，变量值中的 HTML 标签直接渲染：
+
+```yaml
+variables:
+  overview:
+    keywords: "CD38-NAD<sup>+</sup> Axis, NO<sub>3</sub><sup>-</sup>"
+```
+
+```html
+<p>{{overview.keywords}}</p>
+<!-- 渲染为：CD38-NAD<sup>+</sup> Axis, NO<sub>3</sub><sup>-</sup> -->
+```
+
 ### Mustache 列表循环
 
 支持 `{{#items}}...{{/items}}` 语法遍历数组数据：
 
 ```yaml
-# juice.yaml - 配置列表数据
 variables:
   products:
     - name: "产品 A"
@@ -182,12 +244,9 @@ variables:
       tag: "热销"
     - name: "产品 B"
       price: "¥199.00"
-    - name: "产品 C"
-      price: "¥299.00"
 ```
 
 ```html
-<!-- HTML 模板 -->
 {{#products}}
 <div class="product-item">
   <h3>{{name}}</h3>
@@ -196,55 +255,79 @@ variables:
 </div>
 {{/products}}
 
-<!-- 空列表备选内容 -->
 {{^products}}
 <p>暂无商品</p>
 {{/products}}
-
-<!-- 嵌套循环示例 -->
-{{#features}}
-<div class="feature-column">
-  <h4>{{title}}</h4>
-  <ul>
-    {{#items}}
-    <li>{{.}}</li>
-    {{/items}}
-  </ul>
-</div>
-{{/features}}
 ```
 
 | 语法 | 说明 | 示例 |
 |------|------|------|
 | `{{#list}}{{/list}}` | 循环遍历 | `{{#products}}{{name}}{{/products}}` |
 | `{{^list}}{{/list}}` | 反向（空列表时显示） | `{{^products}}暂无{{/products}}` |
-| `{{.}}` | 当前元素 | `{{#.}}{{.}}{{/}}` |
+| `{{.}}` | 当前元素 | `{{#items}}{{.}}{{/items}}` |
 | `{{#var}}{{/var}}` | 条件渲染（仅当有值时显示） | `{{#tag}}{{tag}}{{/tag}}` |
 
 ---
 
-## Windows 右键菜单（自定义图标）
+## 片段组装
 
-注册后，在 `.html` / `.htm` 文件上右键可看到级联子菜单（带自定义图标）：
+### EDM 目录结构
 
 ```
-📧 用 juice 生成邮件 HTML
-  ├── ⚡ 生成邮件 HTML（标准 + 压缩）
-  └── 📂 在此目录打开 PowerShell 7   ← 仅在系统已安装 pwsh 时出现
+edm/
+├── <brand>/                       # 品牌目录
+│   ├── <brand>-template.html      #   品牌模板（含 <tbody id="content">）
+│   └── <series>/                  #   片段系列目录
+│       ├── snippet.html           #     片段 HTML（Mustache 模板片段）
+│       └── juice.yaml             #     片段配置（variables）
 ```
 
-```bash
-# 以管理员身份运行 PowerShell，然后：
-juice --install
+### 片段 HTML 格式
+
+片段是模板中 `<tbody id="content">` 内的内容片段，会被自动插入并调整缩进：
 
-# 卸载：
-juice --uninstall
+```html
+<!-- edm/elabscience/literature/snippet.html -->
+<tr>
+  <td></td>
+  <td colspan="2">
+    <table>
+      <tbody>
+        <tr>
+          <td><img src="{{overview.image}}" /></td>
+          <td><strong>{{overview.title}}</strong></td>
+        </tr>
+      </tbody>
+    </table>
+  </td>
+  <td></td>
+</tr>
 ```
 
-> **注意**：注册/卸载需要 **管理员权限**，请右键"以管理员身份运行"命令行。
-> 注册成功后如菜单未立即出现，重启文件资源管理器（`explorer.exe`）即可。
+### 跨品牌检查
 
-> **图标说明**：自定义图标位于 `icons/juice-icon.ico`，支持 16x16 到 256x256 多种尺寸。
+片段和模板来自不同品牌时，会输出警告但仍继续执行，避免样式错乱。
+
+---
+
+## Windows 右键菜单
+
+注册后，在 `.html` / `.htm` 文件上右键可看到级联子菜单：
+
+```
+📧 用 juice 生成邮件 HTML
+  ├── ⚡ 生成邮件 HTML（标准 + 压缩）    →  juice -f
+  ├── 🧩 邮件片段组装（交互选择模板）    →  juice -s
+  └── 📂 在此目录打开 PowerShell 7      ← 仅在已安装 pwsh 时出现
+```
+
+```bash
+# 以管理员身份运行
+juice --install    # 注册
+juice --uninstall   # 卸载
+```
+
+> **注意**：注册/卸载需要**管理员权限**。注册成功后如菜单未立即出现，重启文件资源管理器（`explorer.exe`）即可。
 
 ---
 
@@ -256,26 +339,24 @@ juice-cli/
 │   └── juice.js               # CLI 入口
 ├── src/
 │   ├── index.js               # 核心逻辑（配置合并、模板处理、双输出）
-│   └── context-menu.js        # Windows 右键菜单注册（自定义图标）
+│   ├── snippet.js             # 片段组装模式 + 交互式提示
+│   └── context-menu.js        # Windows 右键菜单注册
 ├── defaults/
-│   └── juice.yaml             # CLI 内置默认配置（最低优先级基准）
-├── examples/
-│   ├── juice.yaml             # 用户配置示例（含列表数据）
-│   ├── template.html           # HTML 邮件模板示例（含列表循环）
-│   └── *.css                   # 附加样式文件
+│   └── juice.yaml             # CLI 内置默认配置
+├── edm/                       # EDM 模板库（npm 发布时包含）
+│   ├── elabscience/
+│   │   ├── elabscience-template.html
+│   │   └── literature/
+│   │       ├── snippet.html
+│   │       └── juice.yaml
+│   └── procell/
+│       └── procell-template.html
 ├── icons/
-│   └── juice-icon.ico          # 右键菜单自定义图标
+│   └── juice-icon.ico          # 右键菜单图标
 ├── scripts/
-│   ├── generate-icon.js        # 图标生成脚本
 │   └── release.mjs            # 发布脚本
-├── .husky/
-│   └── commit-msg              # Git hooks - 提交信息校验
-├── .commitlintrc.json          # Commitlint 配置
-├── .versionrc                  # Standard-version 配置
-├── .npmrc                      # npm 发布配置
 ├── CHANGELOG.md                # 变更日志（自动生成）
 ├── LICENSE                     # MIT
-├── README.md
 └── package.json
 ```
 
@@ -283,55 +364,24 @@ juice-cli/
 
 ## 发布说明
 
-本项目使用自动化发布流程，包含以下功能：
-
 ### 提交信息规范
 
 使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
 
 ```
-<type>(<scope>): <subject>
-
 feat: 添加新功能
 fix: 修复 bug
 docs: 更新文档
-style: 代码格式调整
-refactor: 重构代码
-perf: 性能优化
-test: 添加测试
-build: 构建系统变更
-ci: CI/CD 配置变更
 chore: 其他变更
-revert: 回退提交
 ```
 
 ### 自动化发布
 
 ```bash
-# 执行一键发布（自动引导整个流程）
-npm run release
-
-# 预览发布（不实际执行）
-npm run release:dry
+npm run release        # 一键发布
+npm run release:dry    # 预览
 ```
 
-**发布流程：**
-1. 检测未提交的文件，询问是否提交
-2. 选择版本更新类型（Major / Minor / Patch）
-3. 确认版本号
-4. 自动更新版本号、生成 CHANGELOG、打 tag
-5. 推送到 origin 和 github 远程仓库
-6. GitHub Actions 自动发布到 npm
-
-### 配置文件
-
-| 文件 | 说明 |
-|------|------|
-| `.commitlintrc.json` | 提交信息校验规则 |
-| `.versionrc` | 版本更新和 CHANGELOG 生成规则 |
-| `.npmrc` | npm 发布配置 |
-| `.husky/commit-msg` | Git hooks 配置 |
-
 ---
 
 ## License

package/bin/juice.js

@@ -11,8 +11,9 @@ program
   .description('生成符合各大邮件平台的内联 CSS HTML 邮件（同时输出标准版 + 压缩版）')
   .version(pkg.version, '-v, --version')
   .option('-f, --file <path>', '输入 HTML 模板文件路径')
-  .option('-c, --config <path>', '配置文件路径（不指定时自动查找输入文件同级目录）')
-  .option('--snippet <path>', '片段 HTML 文件路径：将片段内容插入模板 <tbody id="content"> 中，生成 3 个文件')
+  .option('-s, --snippet <path>', '片段 HTML 文件路径：将片段内容插入模板 <tbody id="content"> 中')
+  .option('-c, --config <path>', '配置文件路径')
+  .option('-n, --name <name>', '片段模式输出文件名（不含扩展名）')
   .option('--install',   '注册 Windows 右键菜单（需管理员权限）')
   .option('--uninstall', '取消 Windows 右键菜单注册（需管理员权限）')
   .addHelpText('before', `
@@ -27,30 +28,44 @@ program
   2. 用户主目录 ~/juice.yaml（如果存在）
   3. 优先配置（-c 指定 或 输入文件同级目录）
 
-普通模式（-f 必选，直接处理单个 HTML）：
-  juice -f my-email.html
-  juice -c project.yaml -f emails/welcome.html
+════════════════════════════════════════════════════════════════
+  使用示例
+════════════════════════════════════════════════════════════════
 
-片段组装模式（--snippet + 模板拼接）：
-  juice --snippet edm/elabscience/literature/snippet.html -f edm/elabscience/elabscience-template.html
-  juice --snippet edm/elabscience/literature/snippet.html          （交互式选择模板）
+  普通模式（CSS 内联 + 压缩，输出 2 个文件）：
+    juice -f my-email.html
+    juice -f my-email.html -c project.yaml
+    juice -f edm/elabscience/elabscience-template.html
 
-交互模式（全交互选择）：
-  juice                                                            （逐步选择品牌、模板、片段、配置）
+  片段模式（片段 + 模板拼接，输出 4 个文件）：
+    juice -s edm/elabscience/literature/snippet.html -f edm/elabscience/elabscience-template.html
+    juice -s edm/elabscience/literature/snippet.html                     （交互选择模板）
+    juice -s snippet.html -f template.html -n my-output                  （自定义输出名）
 
-右键菜单管理：
-  juice --install          （管理员权限，注册右键菜单）
-  juice --uninstall         （管理员权限，卸载右键菜单）
+  交互模式（逐步选择品牌、模板、片段、配置）：
+    juice
 
-普通模式输出文件（与输入文件同目录）：
-  <name>.output.html     CSS 内联 + 变量替换后的标准版
-  <name>.minified.html   在标准版基础上压缩的精简版
+════════════════════════════════════════════════════════════════
+  输出文件说明
+════════════════════════════════════════════════════════════════
 
-片段模式输出文件（当前工作目录）：
-  <name>.raw.html         原始组装（Mustache 未渲染，无 CSS 内联）
-  <name>.html             已渲染（Mustache 变量已替换，无 CSS 内联）
-  <name>.output.html      Juice CSS 内联后
-  <name>.minified.html    压缩版
+  普通模式（与输入文件同目录）：
+    <name>.output.html     CSS 内联 + 变量替换后的标准版
+    <name>.minified.html   压缩版
+
+  片段模式（当前工作目录）：
+    <name>.raw.html         原始组装（Mustache 未渲染，无 CSS 内联）
+    <name>.html             已渲染（Mustache 变量已替换，无 CSS 内联）
+    <name>.output.html      Juice CSS 内联后
+    <name>.minified.html    压缩版
+
+════════════════════════════════════════════════════════════════
+  右键菜单
+════════════════════════════════════════════════════════════════
+
+  在 .html/.htm 文件上右键即可使用：
+    juice --install          （管理员权限，注册右键菜单）
+    juice --uninstall         （管理员权限，卸载右键菜单）
 
 更多信息：https://gitee.com/siriussupreme/juice-cli
 `)
@@ -67,13 +82,14 @@ program
       return;
     }
 
-    // --snippet 模式：片段组装
+    // --snippet / -s 模式：片段组装
     if (options.snippet) {
       const { runSnippetMode } = require('../src/snippet');
       await runSnippetMode({
         snippet: options.snippet,
         template: options.file,
         config: options.config,
+        outputName: options.name,
       });
       return;
     }

package/defaults/juice.yaml

@@ -9,6 +9,10 @@
 #
 # 用户配置文件（~/juice.yaml 或项目 juice.yaml）只需填写需要覆盖的字段即可。
 
+# 设为 false 时，模板变量中的 HTML 标签会被转义（<sup> 变成 &lt;sup&gt;）
+# 默认 true：变量值中的 HTML 标签（如 <sup>、<sub>）直接渲染
+rawHtml: true
+
 # ─── juice CSS 内联选项 ───────────────────────────────────────────────────────
 juice:
   # 处理完成后移除 <style> 标签（推荐 true，提高 Gmail/Outlook 等邮件客户端兼容性）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "juice-email-cli",
-  "version": "2.1.6",
+  "version": "2.1.8",
   "description": "CLI tool to generate email-client-compatible HTML with juice (CSS inlining) + Mustache templating + minification",
   "main": "src/index.js",
   "bin": {

package/src/context-menu.js

@@ -102,14 +102,14 @@ async function registerContextMenu() {
 
   // ── 注册子命令到 CommandStore ─────────────────────────────────────────────
 
-  // 子命令 1：juice 生成
+  // 子命令 1：普通模式 - juice 生成
   const generateCmd = `"${nodePath}" "${scriptPath}" -f "%1"`;
   regAdd(`${SUBCMD_SPACE}\\${subCmd1}`, '', 'REG_SZ', '⚡ 生成邮件 HTML（标准 + 压缩）');
   regAdd(`${SUBCMD_SPACE}\\${subCmd1}`, 'Icon', 'REG_SZ', iconPath);
   regAdd(`${SUBCMD_SPACE}\\${subCmd1}\\command`, '', 'REG_SZ', generateCmd);
 
-  // 子命令 2：片段组装
-  const snippetCmd = `"${nodePath}" "${scriptPath}" --snippet "%1"`;
+  // 子命令 2：片段模式 - 片段组装（交互选择模板）
+  const snippetCmd = `"${nodePath}" "${scriptPath}" -s "%1"`;
   regAdd(`${SUBCMD_SPACE}\\${subCmd2}`, '', 'REG_SZ', '🧩 邮件片段组装（交互选择模板）');
   regAdd(`${SUBCMD_SPACE}\\${subCmd2}`, 'Icon', 'REG_SZ', iconPath);
   regAdd(`${SUBCMD_SPACE}\\${subCmd2}\\command`, '', 'REG_SZ', snippetCmd);
@@ -146,13 +146,11 @@ async function registerContextMenu() {
     chalk.green('  ✔ 右键菜单注册完成！') + '\n\n' +
     `  在 ${chalk.cyan('.html')} / ${chalk.cyan('.htm')} 文件上右键即可看到：\n` +
     `  ${chalk.bold('📧 用 juice 生成邮件 HTML')}\n` +
-    `    ├── ⚡ 生成邮件 HTML（标准 + 压缩）\n` +
-    `    ├── 🧩 邮件片段组装（交互选择模板）\n` +
+    `    ├── ⚡ 生成邮件 HTML（标准 + 压缩）  →  juice -f\n` +
+    `    ├── 🧩 邮件片段组装（交互选择模板） →  juice -s\n` +
     (pwshPath ? `    └── 📂 在此目录打开 PowerShell 7\n` : '') +
     '\n' +
-    chalk.gray('  注意：如菜单未出现，请重启文件资源管理器（explorer.exe）。\n') +
-    chalk.gray('  安装时自动注册失败？请以管理员身份重新运行：\n') +
-    chalk.cyan('    juice --register\n')
+    chalk.gray('  注意：如菜单未出现，请重启文件资源管理器（explorer.exe）。\n')
   );
 }
 

package/src/index.js

@@ -146,8 +146,13 @@ function buildConfig(highPriorityPath, homePath) {
 function processTemplate(inputFile, config) {
   const htmlRaw = fs.readFileSync(inputFile, 'utf8');
 
-  // 1. Mustache 变量替换
+  // 1. Mustache 变量替换（根据 rawHtml 配置决定是否转义 HTML）
+  const originalEscape = Mustache.escape;
+  if (config.rawHtml) {
+    Mustache.escape = (text) => text;
+  }
   const htmlWithVars = Mustache.render(htmlRaw, config.variables || {});
+  Mustache.escape = originalEscape;
 
   // 2. 收集 extraCssFiles
   const basePath = path.dirname(path.resolve(inputFile));

package/src/snippet.js

@@ -141,7 +141,7 @@ function buildSnippetConfig({ priorityConfigPath, cliConfigPath }) {
 
 /**
  * 将 snippet HTML 插入到模板的 <tbody id="content"> 中。
- * 使用深度计数算法处理嵌套 <tbody>。
+ * 使用深度计数算法处理嵌套 <tbody>，并自动调整片段缩进以匹配模板。
  */
 function insertIntoContent(templateHtml, snippetHtml) {
   const openRe = /<tbody[\s>][^>]*\bid\s*=\s*["']content["'][^>]*>/i;
@@ -150,6 +150,18 @@ function insertIntoContent(templateHtml, snippetHtml) {
     throw new Error('模板中未找到 <tbody id="content"> 元素。模板必须包含一个带 id="content" 的 <tbody> 用于插入片段内容。');
   }
 
+  // 检测模板中 <tbody id="content"> 的缩进层级
+  const lineStart = templateHtml.lastIndexOf('\n', match.index) + 1;
+  const tagIndent = match.index - lineStart;
+
+  // 找到插入点后第一个非空行，确定子元素缩进
+  const afterOpen = templateHtml.substring(match.index + match[0].length);
+  const nextLineMatch = afterOpen.match(/\n(\s*)\S/);
+  const childIndent = nextLineMatch ? nextLineMatch[1].length : tagIndent + 2;
+
+  // 调整片段缩进以匹配模板
+  const reindentedSnippet = reindentHtml(snippetHtml, childIndent);
+
   const openTagEnd = match.index + match[0].length;
   let depth = 1;
   let searchPos = openTagEnd;
@@ -172,7 +184,8 @@ function insertIntoContent(templateHtml, snippetHtml) {
     } else {
       depth--;
       if (depth === 0) {
-        return templateHtml.substring(0, openTagEnd) + '\n' + snippetHtml + '\n' + templateHtml.substring(nextClose.index);
+        const indent = '\n' + ' '.repeat(tagIndent);
+        return templateHtml.substring(0, openTagEnd) + '\n' + reindentedSnippet + indent + templateHtml.substring(nextClose.index);
       }
       searchPos = nextClose.index + 1;
     }
@@ -181,10 +194,41 @@ function insertIntoContent(templateHtml, snippetHtml) {
   throw new Error('无法找到 id="content" 对应的闭合 </tbody> 标签，模板 HTML 可能存在标签不匹配问题。');
 }
 
+/**
+ * 重新调整 HTML 片段的缩进，使其最外层元素对齐到目标缩进层级
+ */
+function reindentHtml(html, targetIndent) {
+  const lines = html.split('\n');
+
+  // 找到片段中非空行的最小缩进
+  let minIndent = Infinity;
+  for (const line of lines) {
+    if (line.trim().length > 0) {
+      const indent = line.length - line.trimStart().length;
+      if (indent < minIndent) minIndent = indent;
+    }
+  }
+  if (minIndent === Infinity) minIndent = 0;
+
+  const delta = targetIndent - minIndent;
+  if (delta === 0) return html;
+
+  const prefix = ' '.repeat(Math.max(0, delta));
+
+  return lines.map((line) => {
+    if (line.trim().length === 0) return '';
+    if (delta > 0) {
+      return prefix + line;
+    } else {
+      return line.substring(Math.min(-delta, line.length - line.trimStart().length));
+    }
+  }).join('\n');
+}
+
 // ─── 输出路径 ─────────────────────────────────────────────────────────────────
 
-function resolveSnippetOutputPaths(snippetPath, cwd) {
-  const name = path.parse(snippetPath).name;
+function resolveSnippetOutputPaths(outputBaseName, cwd) {
+  const name = outputBaseName;
   return {
     raw: path.join(cwd, name + '.raw.html'),
     normal: path.join(cwd, name + '.html'),
@@ -202,18 +246,23 @@ function resolveSnippetOutputPaths(snippetPath, cwd) {
  *   3. Juice CSS 内联 → .output.html
  *   4. 压缩 → .minified.html
  */
-async function assembleSnippet({ snippetPath, templatePath, config, layers, cwd }) {
+async function assembleSnippet({ snippetPath, templatePath, config, layers, cwd, outputBaseName }) {
   const templateHtml = fs.readFileSync(templatePath, 'utf8');
   const snippetRaw = fs.readFileSync(snippetPath, 'utf8');
-  const outPaths = resolveSnippetOutputPaths(snippetPath, cwd);
-  const variables = config.variables || {};
+  const outPaths = resolveSnippetOutputPaths(outputBaseName, cwd);
+  const variables = Object.assign({}, config.variables || {});
 
   // 1. 未渲染的片段插入模板 → .raw.html（Mustache 标签保留，无 juice）
-  const rawHtml = insertIntoContent(templateHtml, snippetRaw);
-  fs.writeFileSync(outPaths.raw, rawHtml, 'utf8');
+  const rawMarkup = insertIntoContent(templateHtml, snippetRaw);
+  fs.writeFileSync(outPaths.raw, rawMarkup, 'utf8');
 
   // 2. Mustache 渲染合并 HTML → .html（已渲染，无 juice 内联）
-  const renderedHtml = Mustache.render(rawHtml, variables);
+  const originalEscape = Mustache.escape;
+  if (config.rawHtml) {
+    Mustache.escape = (text) => text;
+  }
+  const renderedHtml = Mustache.render(rawMarkup, variables);
+  Mustache.escape = originalEscape;
   fs.writeFileSync(outPaths.normal, renderedHtml, 'utf8');
 
   // 3. 收集模板目录的额外 CSS + Juice CSS 内联 → .output.html
@@ -239,7 +288,7 @@ async function assembleSnippet({ snippetPath, templatePath, config, layers, cwd
     `  ${chalk.bold('模板：')}  ${chalk.cyan(templatePath)}\n` +
     `  ${chalk.bold('配置层（低→高）：')}\n${layerLines}\n` +
     `  ${chalk.bold('输出：')}\n` +
-    `    ${chalk.green('·')} 原始组装  ${chalk.cyan(outPaths.raw)}  ${chalk.gray('(' + fmtSize(rawHtml) + ')')}\n` +
+    `    ${chalk.green('·')} 原始组装  ${chalk.cyan(outPaths.raw)}  ${chalk.gray('(' + fmtSize(rawMarkup) + ')')}\n` +
     `    ${chalk.green('·')} 已渲染    ${chalk.cyan(outPaths.normal)}  ${chalk.gray('(' + fmtSize(renderedHtml) + ')')}\n` +
     `    ${chalk.green('·')} 内联后    ${chalk.cyan(outPaths.output)}  ${chalk.gray('(' + fmtSize(processed) + ')')}\n` +
     `    ${chalk.green('·')} 压缩版    ${chalk.cyan(outPaths.minified)}  ${chalk.gray('(' + fmtSize(minified) + '，节省 ' + savings(processed, minified) + ')')}`
@@ -357,8 +406,82 @@ async function promptTemplate(templateFiles) {
   });
 }
 
+// ─── 输出文件名处理 ───────────────────────────────────────────────────────────
+
+/**
+ * 检查指定 baseName 在 cwd 下是否已有输出文件冲突
+ * 返回冲突的文件路径列表
+ */
+function checkOutputConflicts(baseName, cwd) {
+  const suffixes = ['.raw.html', '.html', '.output.html', '.minified.html'];
+  return suffixes
+    .map((s) => path.join(cwd, baseName + s))
+    .filter((p) => fs.existsSync(p));
+}
+
+/**
+ * 查找下一个可用版本号（baseName-v1, baseName-v2, ...）
+ */
+function findNextVersion(baseName, cwd) {
+  let v = 1;
+  while (true) {
+    const candidate = baseName + '-v' + v;
+    if (checkOutputConflicts(candidate, cwd).length === 0) {
+      return candidate;
+    }
+    v++;
+  }
+}
+
+/**
+ * 交互式输出文件名提示
+ * 返回最终确定的 baseName
+ */
+async function promptOutputName(defaultBaseName, cwd) {
+  const { input, select } = await import('@inquirer/prompts');
+
+  let baseName = await input({
+    message: '请输入输出文件名：',
+    default: defaultBaseName,
+  });
+
+  // 冲突检测循环
+  while (true) {
+    const conflicts = checkOutputConflicts(baseName, cwd);
+    if (conflicts.length === 0) break;
+
+    console.log(chalk.yellow(`\n  ⚠  以下文件已存在：`));
+    conflicts.forEach((f) => console.log(chalk.gray(`      ${path.basename(f)}`)));
+
+    const action = await select({
+      message: '文件已存在，请选择处理方式：',
+      choices: [
+        { name: '覆盖现有文件', value: 'overwrite' },
+        { name: `自动版本号（${findNextVersion(baseName, cwd)}）`, value: 'version' },
+        { name: '重新输入文件名', value: 'rename' },
+      ],
+    });
+
+    if (action === 'overwrite') {
+      break;
+    } else if (action === 'version') {
+      baseName = findNextVersion(baseName, cwd);
+      console.log(chalk.green(`  ✔ 已自动生成版本号：${baseName}`));
+      break;
+    } else {
+      baseName = await input({
+        message: '请重新输入输出文件名：',
+        default: baseName,
+      });
+    }
+  }
+
+  return baseName;
+}
+
 async function promptConfirm(summary) {
   const { confirm } = await import('@inquirer/prompts');
+  const outPaths = resolveSnippetOutputPaths(summary.outputBaseName, summary.outputDir);
   console.log('\n' + chalk.cyan('═══════════════════════════════════════════'));
   console.log(chalk.bold('  片段组装汇总'));
   console.log(chalk.cyan('═══════════════════════════════════════════'));
@@ -369,8 +492,8 @@ async function promptConfirm(summary) {
   console.log(`  配置 YAML：     ${chalk.green(summary.configFile)}`);
   console.log(chalk.gray('───────────────────────────────────────────'));
   console.log(`  输出目录：      ${chalk.cyan(summary.outputDir)}`);
+  console.log(`  输出文件名：    ${chalk.green(summary.outputBaseName)}`);
   console.log(`  输出文件：`);
-  const outPaths = resolveSnippetOutputPaths(summary.snippetPath, summary.outputDir);
   console.log(`    ${chalk.green('·')} ${path.basename(outPaths.raw)}  ${chalk.gray('(未渲染，无 CSS 内联)')}`);
   console.log(`    ${chalk.green('·')} ${path.basename(outPaths.normal)}  ${chalk.gray('(已渲染，无 CSS 内联)')}`);
   console.log(`    ${chalk.green('·')} ${path.basename(outPaths.output)}  ${chalk.gray('(Juice CSS 内联)')}`);
@@ -392,7 +515,7 @@ async function promptConfirm(summary) {
  *   - 配置文件：自动检测片段目录下的 juice.yaml / juice.yml，-c 可覆盖
  *   - 合并顺序：项目默认 → 用户目录 → 片段目录配置 → CLI -c
  */
-async function runSnippetMode({ snippet, template, config: cliConfigPath }) {
+async function runSnippetMode({ snippet, template, config: cliConfigPath, outputName }) {
   const snippetPath = path.resolve(snippet);
   if (!fs.existsSync(snippetPath)) {
     console.error(chalk.red(`片段文件不存在：${snippetPath}`));
@@ -437,12 +560,44 @@ async function runSnippetMode({ snippet, template, config: cliConfigPath }) {
 
   const { config, layers } = buildSnippetConfig({ priorityConfigPath, cliConfigPath });
 
+  // 确定输出文件名
+  const defaultBaseName = outputName || path.parse(templatePath).name;
+  let outputBaseName;
+
+  if (outputName) {
+    // 命令行指定了 --name，检查冲突，有冲突则自动版本号
+    const conflicts = checkOutputConflicts(defaultBaseName, process.cwd());
+    if (conflicts.length > 0) {
+      outputBaseName = findNextVersion(defaultBaseName, process.cwd());
+      console.warn(chalk.yellow(
+        `\n⚠  文件冲突，自动使用版本号：${outputBaseName}`
+      ));
+    } else {
+      outputBaseName = defaultBaseName;
+    }
+  } else if (template) {
+    // 非交互模式（--snippet + -f 均指定），自动版本号
+    const conflicts = checkOutputConflicts(defaultBaseName, process.cwd());
+    if (conflicts.length > 0) {
+      outputBaseName = findNextVersion(defaultBaseName, process.cwd());
+      console.warn(chalk.yellow(
+        `\n⚠  文件冲突，自动使用版本号：${outputBaseName}`
+      ));
+    } else {
+      outputBaseName = defaultBaseName;
+    }
+  } else {
+    // 交互模式（--snippet 单独指定），提示用户输入
+    outputBaseName = await promptOutputName(defaultBaseName, process.cwd());
+  }
+
   await assembleSnippet({
     snippetPath,
     templatePath,
     config,
     layers,
     cwd: process.cwd(),
+    outputBaseName,
   });
 }
 
@@ -493,7 +648,11 @@ async function runInteractiveMode({ config: cliConfigPath }) {
     configFileName = configChoice.name;
   }
 
-  // 6. 汇总确认
+  // 6. 确定输出文件名
+  const defaultBaseName = path.parse(templateChoice.path).name;
+  const outputBaseName = await promptOutputName(defaultBaseName, process.cwd());
+
+  // 7. 汇总确认
   const confirmed = await promptConfirm({
     brand: brand.name,
     templateFile: templateChoice.name,
@@ -502,6 +661,7 @@ async function runInteractiveMode({ config: cliConfigPath }) {
     configFile: configFileName,
     snippetPath: snippetFile.path,
     outputDir: process.cwd(),
+    outputBaseName,
   });
 
   if (!confirmed) {
@@ -509,7 +669,7 @@ async function runInteractiveMode({ config: cliConfigPath }) {
     return;
   }
 
-  // 7. 构建配置并执行
+  // 8. 构建配置并执行
   const { config, layers } = buildSnippetConfig({ priorityConfigPath, cliConfigPath });
 
   await assembleSnippet({
@@ -518,6 +678,7 @@ async function runInteractiveMode({ config: cliConfigPath }) {
     config,
     layers,
     cwd: process.cwd(),
+    outputBaseName,
   });
 }