@v1hz/md2docx 2.3.0 → 2.4.0

package/README.md

@@ -23,6 +23,7 @@
 | 标题层级归一化    | 将最浅标题归一化为 H1，并修复标题层级跳跃                        |
 | 标题编号          | 生成 `1`、`1.1`、`1.1.1` 等编号，并可剥离常见的已有中英文编号    |
 | 表格与图片编号    | 自动生成“表 1”“图 1：标题”等题注                                 |
+| 图片尺寸限制      | 按自然尺寸等比缩小超过最大宽度或高度的图片                       |
 | Mermaid 图表      | 使用 beautiful-mermaid 和 resvg-wasm 将 Mermaid 渲染为高 DPI PNG |
 | Word 样式         | 支持受控语义化配置和完整底层样式，也可从现有 DOCX 提取样式       |
 | Markdown 格式化   | 可只运行预处理流水线，输出格式化后的 Markdown                    |
@@ -37,7 +38,7 @@
 前置依赖：
 
 - [Node.js 22.12+](https://nodejs.org/)
-- [Pandoc](https://pandoc.org/installing.html)，并确保 `pandoc` 可通过 `PATH` 调用
+- [Pandoc](https://pandoc.org/installing.html)，并确保 `pandoc` 可通过 `PATH` 调用；图片尺寸限制需要 Pandoc 3.1.13+
 
 ```bash
 npm install -g @v1hz/md2docx
@@ -58,26 +59,27 @@ npx @v1hz/md2docx report.md
 md2docx report.md
 
 # 使用任何转换选项时，输入必须通过 --file 指定
-md2docx --file report.md --output output/report.docx --force
+md2docx --file report.md --output output/report.docx
 
-# 使用自定义配置和样式
-md2docx -f report.md -c config.json -s style.json
+# 使用自定义配置、底层样式和语义化样式配置
+md2docx -f report.md -c config.json --style-raw style-raw.json --style-config style-config.json
 
 # 只执行 Markdown 预处理
 md2docx format -f report.md
 
-# 导出内置默认配置和样式
+# 导出内置默认配置、底层样式和语义化样式配置
 md2docx export config
-md2docx export style
+md2docx export style-raw
+md2docx export style-config
 
 # 从现有 DOCX 提取样式
-md2docx export style -f template.docx
+md2docx export style-raw -f template.docx
 
 # 删除 ~/.md2docx 中的中间文件和缓存
 md2docx clean
 ```
 
-所有写文件命令默认拒绝覆盖已有文件。确认覆盖时显式传入 `--force`。
+所有写文件命令默认覆盖已有输出。
 
 ## CLI 参考
 
@@ -86,29 +88,30 @@ md2docx <markdown>
 md2docx -f <markdown> [转换选项]
 md2docx format -f <markdown> [选项]
 md2docx export config [选项]
-md2docx export style [选项]
+md2docx export style-raw [选项]
+md2docx export style-config [选项]
 md2docx clean
 ```
 
 ### 转换
 
-| 参数                  | 说明                                     |
-| --------------------- | ---------------------------------------- |
-| `<markdown>`          | 位置参数；仅在没有其他转换选项时允许使用 |
-| `-f, --file <path>`   | Markdown 输入文件                        |
-| `-c, --config <path>` | 自定义配置 JSON                          |
-| `-s, --style <path>`  | 语义化样式配置或完整底层样式 JSON        |
-| `-o, --output <path>` | DOCX 输出路径                            |
-| `--force`             | 覆盖已有输出                             |
-| `-h, --help`          | 显示帮助                                 |
-| `-v, --version`       | 显示版本号                               |
+| 参数                    | 说明                                     |
+| ----------------------- | ---------------------------------------- |
+| `<markdown>`            | 位置参数；仅在没有其他转换选项时允许使用 |
+| `-f, --file <path>`     | Markdown 输入文件                        |
+| `-c, --config <path>`   | 自定义配置 JSON                          |
+| `--style-raw <path>`    | 完整底层 Word 样式 JSON                  |
+| `--style-config <path>` | 受控语义化样式配置 JSON                  |
+| `-o, --output <path>`   | DOCX 输出路径                            |
+| `-h, --help`            | 显示帮助                                 |
+| `-v, --version`         | 显示版本号                               |
 
-位置参数不能和 `--file`、`--config`、`--style`、`--output` 或 `--force` 混用。例如：
+位置参数不能和 `--file`、`--config`、`--style-raw`、`--style-config` 或 `--output` 混用。例如：
 
 ```bash
 md2docx report.md                 # 正确
-md2docx report.md --force         # 错误
-md2docx -f report.md --force      # 正确
+md2docx report.md -o report.docx  # 错误
+md2docx -f report.md -o report.docx # 正确
 ```
 
 ### format
@@ -120,16 +123,16 @@ md2docx -f report.md --force      # 正确
 | `-f, --file <path>`   | 必填，Markdown 输入文件                     |
 | `-c, --config <path>` | 自定义配置 JSON                             |
 | `-o, --output <path>` | 输出 Markdown，默认 `<文件名>_formatted.md` |
-| `--force`             | 覆盖已有输出                                |
 
 ### export
 
 ```bash
-md2docx export config [-o config.json] [--force]
-md2docx export style [-f template.docx] [-o style.json] [--force]
+md2docx export config [-o config.json]
+md2docx export style-raw [-f template.docx] [-o style-raw.json]
+md2docx export style-config [-o style-config.json]
 ```
 
-`export config` 导出内置默认配置。`export style` 不带 `--file` 时导出内置默认样式；指定 DOCX 时从该文档提取样式。
+`export config` 导出内置 Markdown 处理配置。`export style-raw` 不带 `--file` 时导出内置底层 Word 样式；指定 DOCX 时从该文档提取底层样式。`export style-config` 导出默认语义化样式配置。
 
 ### clean
 
@@ -153,8 +156,9 @@ md2docx report.md                     → ./report.docx
 md2docx -f report.md                  → ./report.docx
 md2docx format -f report.md           → ./report_formatted.md
 md2docx export config                 → ./config.json
-md2docx export style                  → ./style.json
-md2docx export style -f template.docx → ./template_style.json
+md2docx export style-raw                  → ./style-raw.json
+md2docx export style-raw -f template.docx → ./template_style-raw.json
+md2docx export style-config               → ./style-config.json
 ```
 
 ## 中间文件与缓存
@@ -170,8 +174,9 @@ md2docx export style -f template.docx → ./template_style.json
 ├── resources/
 │   ├── config.json
 │   ├── style-config.json
-│   ├── style.json
-│   └── add-inline-code.lua
+│   ├── style-raw.json
+│   ├── add-inline-code.lua
+│   └── limit-image-size.lua
 └── style/
     └── <样式内容哈希>.docx
 ```
@@ -210,19 +215,23 @@ CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
 | `renderMermaid.enabled`          | 将 Mermaid 渲染为 PNG                          | `true`                |
 | `renderMermaid.theme`            | beautiful-mermaid 主题                         | `"tokyo-night-light"` |
 | `renderMermaid.density`          | PNG 输出 DPI，最小值 72                        | `200`                 |
+| `imageSize.enabled`              | 等比缩小超过尺寸限制的图片                     | `true`                |
+| `imageSize.maxWidthCm`           | DOCX 图片最大宽度（厘米）                      | `15.5`                |
+| `imageSize.maxHeightCm`          | DOCX 图片最大高度（厘米）                      | `22`                  |
 | `removeThematicBreaks.enabled`   | 移除 `---`、`***`、`___` 等分隔符行            | `true`                |
 
+图片尺寸限制在 Pandoc 生成 DOCX 前通过 Lua filter 应用。程序读取图片像素尺寸和 DPI，仅缩小超限图片，不会放大小图；宽度和高度使用同一缩放比例。Markdown 中已经显式设置 `width` 或 `height` 的图片视为用户覆盖，不应用全局限制。单张图片无法读取尺寸时会输出警告并继续转换。
+
 ## 样式定制
 
 普通用户推荐使用受控的语义化样式配置，只修改程序明确开放的高频选项。其余颜色、尺寸、对齐方式、间距和 Word 样式继承关系继续由内置预设管理。
 
-仓库中的 `config/style-config.json` 是可直接复制和修改的默认配置，`config/style-config.schema.json` 用于编辑器提示和校验。未指定 `--style` 时，转换会自动加载内嵌的默认 `style-config.json`，再将它编译到内置底层样式；不需要手工传入 `-s`。
+仓库中的 `config/style-config.json` 是可直接复制和修改的默认配置，`config/style-config.schema.json` 用于编辑器提示和校验。完整底层 Word 样式位于 `config/style-raw.json`。
 
 ```json
 {
   "$schema": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
   "schemaVersion": 1,
-  "preset": "default",
   "options": {
     "body": {
       "firstLineIndent": false
@@ -245,18 +254,27 @@ CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
 将配置保存为 `style-config.json` 后使用：
 
 ```bash
-md2docx -f report.md -s style-config.json
+md2docx -f report.md --style-config style-config.json
 ```
 
-字段缺失表示继承预设；`true` 表示使用预设效果；`false` 表示显式关闭。当前只开放正文首行缩进、一级标题另起一页、行内代码背景和代码块外框。完整设计见 [`docs/style-config-design.md`](docs/style-config-design.md)。
+字段缺失表示继承底层样式；`true` 表示显式启用完整效果；`false` 表示显式关闭。当前只开放正文首行缩进、一级标题另起一页、行内代码背景和代码块外框。完整设计见 [`docs/style-config-design.md`](docs/style-config-design.md)。
+
+转换时按以下规则选择输入：
 
-`config/style.json` 仍定义完整的底层 DOCX 样式，包括标题、段落、字符和表格样式。转换时，项目先将语义化配置编译到底层样式，再用 `docx` 生成 reference DOCX，最后通过 Pandoc 的 `--reference-doc` 应用样式。现有完整样式 JSON 可继续直接传给 `--style`。
+| 参数                | 行为                                |
+| ------------------- | ----------------------------------- |
+| 都不指定            | 默认 raw + 默认 config              |
+| 仅 `--style-raw`    | 直接使用用户 raw，不应用默认 config |
+| 仅 `--style-config` | 用户 config 应用到默认 raw          |
+| 两者都指定          | 用户 config 应用到用户 raw          |
+
+最终有效的底层样式用于生成 reference DOCX，并通过 Pandoc 的 `--reference-doc` 应用。`--style-raw` 和 `--style-config` 类型固定，不能互换。
 
 ### 从现有 DOCX 提取
 
 ```bash
-md2docx export style -f template.docx
-md2docx -f report.md -s template_style.json
+md2docx export style-raw -f template.docx
+md2docx -f report.md --style-raw template_style-raw.json
 ```
 
 ### 高级手动维护
@@ -323,7 +341,7 @@ numberPictures()
     ↓
 生成或复用 reference DOCX
     ↓
-Pandoc + Lua filter
+Pandoc + 行内代码/图片尺寸 Lua filter
     ↓
 DOCX
 ```
@@ -386,14 +404,6 @@ pandoc --version
 
 如果命令不存在，请从 [Pandoc 官方安装页](https://pandoc.org/installing.html) 安装，并重新打开终端使 `PATH` 生效。
 
-### 输出文件已存在
-
-默认不会覆盖文件。确认目标可以覆盖后使用：
-
-```bash
-md2docx -f report.md --force
-```
-
 ### 从其他目录转换时图片缺失
 
 相对图片路径应以原始 Markdown 文件为基准：

package/config/config.json

@@ -23,6 +23,11 @@
     "theme": "tokyo-night-light",
     "density": 200
   },
+  "imageSize": {
+    "enabled": true,
+    "maxWidthCm": 12,
+    "maxHeightCm": 12
+  },
   "detectTitle": {
     "enabled": true,
     "strategy": "first-h1"

package/config/config.schema.json

@@ -117,6 +117,31 @@
       },
       "required": ["enabled", "theme", "density"]
     },
+    "imageSize": {
+      "description": "DOCX 图片尺寸限制",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "description": "按图片自然尺寸等比缩小超限图片",
+          "type": "boolean",
+          "default": true
+        },
+        "maxWidthCm": {
+          "description": "图片最大宽度（厘米）",
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "default": 15.5
+        },
+        "maxHeightCm": {
+          "description": "图片最大高度（厘米）",
+          "type": "number",
+          "exclusiveMinimum": 0,
+          "default": 22
+        }
+      },
+      "required": ["enabled", "maxWidthCm", "maxHeightCm"]
+    },
     "detectTitle": {
       "description": "文档标题",
       "type": "object",
@@ -162,6 +187,7 @@
     "normalizeHeadings",
     "numberHeadings",
     "renderMermaid",
+    "imageSize",
     "detectTitle",
     "removeThematicBreaks"
   ]

package/config/lua/limit-image-size.lua

@@ -0,0 +1,93 @@
+local max_width_cm
+local max_height_cm
+local size_cache = {}
+local warned = {}
+
+local function warn_once(source, message)
+  if warned[source] then
+    return
+  end
+  warned[source] = true
+  local text = "无法限制图片尺寸 " .. source .. "：" .. message
+  if pandoc.log and pandoc.log.warn then
+    pandoc.log.warn(text)
+  else
+    io.stderr:write("[WARNING] " .. text .. "\n")
+  end
+end
+
+local function metadata_number(meta, key)
+  local value = meta[key]
+  if value == nil then
+    return nil
+  end
+  return tonumber(pandoc.utils.stringify(value))
+end
+
+local function read_config(meta)
+  max_width_cm = metadata_number(meta, "md2docx-image-max-width-cm")
+  max_height_cm = metadata_number(meta, "md2docx-image-max-height-cm")
+end
+
+local function image_size(source)
+  local cached = size_cache[source]
+  if cached ~= nil then
+    return cached or nil
+  end
+  if pandoc.image == nil or pandoc.image.size == nil then
+    warn_once(source, "当前 Pandoc 不支持 pandoc.image.size，请升级到 3.1.13 或更高版本")
+    size_cache[source] = false
+    return nil
+  end
+
+  local fetched, _, contents = pcall(pandoc.mediabag.fetch, source)
+  if not fetched or contents == nil then
+    warn_once(source, fetched and "未读取到图片内容" or tostring(_))
+    size_cache[source] = false
+    return nil
+  end
+
+  local measured, size = pcall(pandoc.image.size, contents, PANDOC_WRITER_OPTIONS)
+  if not measured then
+    warn_once(source, tostring(size))
+    size_cache[source] = false
+    return nil
+  end
+
+  size_cache[source] = size
+  return size
+end
+
+local function limit_image(image)
+  if max_width_cm == nil or max_height_cm == nil then
+    return nil
+  end
+  if image.attributes.width ~= nil or image.attributes.height ~= nil then
+    return nil
+  end
+
+  local size = image_size(image.src)
+  if size == nil then
+    return nil
+  end
+
+  local fallback_dpi = PANDOC_WRITER_OPTIONS.dpi or 96
+  local horizontal_dpi = size.dpi_horz > 0 and size.dpi_horz or fallback_dpi
+  local vertical_dpi = size.dpi_vert > 0 and size.dpi_vert or fallback_dpi
+  local width_cm = size.width / horizontal_dpi * 2.54
+  local height_cm = size.height / vertical_dpi * 2.54
+  local scale = math.min(1, max_width_cm / width_cm, max_height_cm / height_cm)
+
+  if scale >= 1 then
+    return nil
+  end
+
+  image.attributes.width = string.format("%.4fcm", width_cm * scale)
+  image.attributes.height = string.format("%.4fcm", height_cm * scale)
+  return image
+end
+
+return {
+  { Meta = read_config },
+  { Image = limit_image },
+}

package/config/style-config.json

@@ -1,7 +1,6 @@
 {
   "$schema": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
   "schemaVersion": 1,
-  "preset": "default",
   "options": {
     "body": {
       "firstLineIndent": true

package/config/style-config.schema.json

@@ -4,7 +4,7 @@
   "title": "md2docx 语义化样式配置",
   "type": "object",
   "additionalProperties": false,
-  "required": ["schemaVersion", "preset"],
+  "required": ["schemaVersion"],
   "properties": {
     "$schema": {
       "type": "string"
@@ -12,9 +12,6 @@
     "schemaVersion": {
       "const": 1
     },
-    "preset": {
-      "const": "default"
-    },
     "options": {
       "type": "object",
       "additionalProperties": false,

package/dist/index.js

@@ -128401,7 +128401,7 @@ import { fileURLToPath as fileURLToPath3 } from "node:url";
 // package.json
 var package_default = {
   name: "@v1hz/md2docx",
-  version: "2.3.0",
+  version: "2.4.0",
   description: "基于 pandoc 的 Markdown 转 Word 工具，自动格式化 Markdown，支持自定义样式，AI 友好，用户友好。",
   keywords: [
     "converter",
@@ -128471,8 +128471,8 @@ var package_default = {
 // src/cli.ts
 function createProgram(version, actions) {
   const program2 = new Command;
-  program2.name("md2docx").description("将 Markdown 转换为 Word 文档").version(version, "-v, --version", "显示版本号").helpOption("-h, --help", "显示帮助").helpCommand(false).showHelpAfterError("使用 --help 查看帮助").showSuggestionAfterError().enablePositionalOptions().argument("[markdown]", "Markdown 文件（仅无其他转换选项时）").option("-f, --file <path>", "Markdown 文件").option("-c, --config <path>", "自定义配置文件").option("-s, --style <path>", "自定义底层样式或语义化样式配置").option("-o, --output <path>", "输出 DOCX 文件").option("--force", "覆盖已有文件").action(async function(markdown, options) {
-    const hasAdditionalOptions = options.config !== undefined || options.style !== undefined || options.output !== undefined || options.force !== undefined;
+  program2.name("md2docx").description("将 Markdown 转换为 Word 文档").version(version, "-v, --version", "显示版本号").helpOption("-h, --help", "显示帮助").helpCommand(false).showHelpAfterError("使用 --help 查看帮助").showSuggestionAfterError().enablePositionalOptions().argument("[markdown]", "Markdown 文件（仅无其他转换选项时）").option("-f, --file <path>", "Markdown 文件").option("-c, --config <path>", "自定义配置文件").option("--style-raw <path>", "自定义底层 Word 样式").option("--style-config <path>", "自定义语义化样式配置").option("-o, --output <path>", "输出 DOCX 文件").action(async function(markdown, options) {
+    const hasAdditionalOptions = options.config !== undefined || options.styleRaw !== undefined || options.styleConfig !== undefined || options.output !== undefined;
     if (markdown !== undefined) {
       if (options.file !== undefined || hasAdditionalOptions) {
         this.error("位置参数不能与转换选项同时使用；使用选项时请通过 -f, --file 指定 Markdown 文件");
@@ -128493,11 +128493,13 @@ function createProgram(version, actions) {
     this.help({ error: true });
   });
   exportCommand.exitOverride();
-  const exportConfigCommand = exportCommand.command("config").description("导出默认配置").helpOption("-h, --help", "显示帮助").option("-o, --output <path>", "输出 JSON 文件，默认 ./config.json").option("--force", "覆盖已有文件").action(actions.exportConfig);
+  const exportConfigCommand = exportCommand.command("config").description("导出默认配置").helpOption("-h, --help", "显示帮助").option("-o, --output <path>", "输出 JSON 文件，默认 ./config.json").action(actions.exportConfig);
   exportConfigCommand.exitOverride();
-  const exportStyleCommand = exportCommand.command("style").description("导出默认样式，或从 DOCX 提取样式").helpOption("-h, --help", "显示帮助").option("-f, --file <path>", "用于提取样式的 DOCX 文件").option("-o, --output <path>", "输出 JSON 文件").option("--force", "覆盖已有文件").action(actions.exportStyle);
-  exportStyleCommand.exitOverride();
-  const formatCommand = program2.command("format").description("预处理并格式化 Markdown").helpOption("-h, --help", "显示帮助").requiredOption("-f, --file <path>", "Markdown 文件").option("-c, --config <path>", "自定义配置文件").option("-o, --output <path>", "输出 Markdown 文件").option("--force", "覆盖已有文件").action(actions.format);
+  const exportStyleRawCommand = exportCommand.command("style-raw").description("导出默认底层 Word 样式，或从 DOCX 提取底层样式").helpOption("-h, --help", "显示帮助").option("-f, --file <path>", "用于提取底层样式的 DOCX 文件").option("-o, --output <path>", "输出 JSON 文件").action(actions.exportStyleRaw);
+  exportStyleRawCommand.exitOverride();
+  const exportStyleConfigCommand = exportCommand.command("style-config").description("导出默认语义化样式配置").helpOption("-h, --help", "显示帮助").option("-o, --output <path>", "输出 JSON 文件，默认 ./style-config.json").action(actions.exportStyleConfig);
+  exportStyleConfigCommand.exitOverride();
+  const formatCommand = program2.command("format").description("预处理并格式化 Markdown").helpOption("-h, --help", "显示帮助").requiredOption("-f, --file <path>", "Markdown 文件").option("-c, --config <path>", "自定义配置文件").option("-o, --output <path>", "输出 Markdown 文件").action(actions.format);
   formatCommand.exitOverride();
   const cleanCommand = program2.command("clean").description("清除 ~/.md2docx 中的预处理文件和样式缓存").helpOption("-h, --help", "显示帮助").action(async () => {
     await actions.clean();
@@ -128595,6 +128597,10 @@ function validateConfig(value, path2) {
   if (!Number.isInteger(mermaid.density) || mermaid.density < 72) {
     invalidConfig(path2, "renderMermaid.density", "必须是不小于 72 的整数");
   }
+  const imageSize = expectRecord(root.imageSize, path2, "imageSize");
+  expectBoolean(imageSize.enabled, path2, "imageSize.enabled");
+  expectPositiveNumber(imageSize.maxWidthCm, path2, "imageSize.maxWidthCm");
+  expectPositiveNumber(imageSize.maxHeightCm, path2, "imageSize.maxHeightCm");
   validateEnabled(root.removeThematicBreaks, path2, "removeThematicBreaks");
   const title = expectRecord(root.detectTitle, path2, "detectTitle");
   expectBoolean(title.enabled, path2, "detectTitle.enabled");
@@ -128629,6 +128635,12 @@ function expectString(value, path2, field) {
     invalidConfig(path2, field, "必须是字符串");
   return value;
 }
+function expectPositiveNumber(value, path2, field) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    invalidConfig(path2, field, "必须是大于 0 的有限数字");
+  }
+  return value;
+}
 function invalidConfig(path2, field, reason) {
   throw new Error(`配置文件无效：${path2}
 位置：${field}
@@ -128652,11 +128664,7 @@ function resolveOutputPath(path2, defaultName, extensions, label) {
   assertExtension(resolved, extensions, label);
   return resolved;
 }
-function prepareOutput(path2, force) {
-  if (existsSync2(path2) && !force) {
-    throw new Error(`输出文件已存在：${path2}
-使用 --force 覆盖现有文件`);
-  }
+function prepareOutput(path2) {
   mkdirSync(dirname2(path2), { recursive: true });
 }
 function assertExtension(path2, extensions, label) {
@@ -146108,6 +146116,11 @@ var config_default = `{
     "theme": "tokyo-night-light",
     "density": 200
   },
+  "imageSize": {
+    "enabled": true,
+    "maxWidthCm": 12,
+    "maxHeightCm": 12
+  },
   "detectTitle": {
     "enabled": true,
     "strategy": "first-h1"
@@ -146118,6 +146131,102 @@ var config_default = `{
 }
 `;
 
+// config/lua/limit-image-size.lua
+var limit_image_size_default = `local max_width_cm
+local max_height_cm
+local size_cache = {}
+local warned = {}
+
+local function warn_once(source, message)
+  if warned[source] then
+    return
+  end
+  warned[source] = true
+  local text = "无法限制图片尺寸 " .. source .. "：" .. message
+  if pandoc.log and pandoc.log.warn then
+    pandoc.log.warn(text)
+  else
+    io.stderr:write("[WARNING] " .. text .. "\\n")
+  end
+end
+
+local function metadata_number(meta, key)
+  local value = meta[key]
+  if value == nil then
+    return nil
+  end
+  return tonumber(pandoc.utils.stringify(value))
+end
+
+local function read_config(meta)
+  max_width_cm = metadata_number(meta, "md2docx-image-max-width-cm")
+  max_height_cm = metadata_number(meta, "md2docx-image-max-height-cm")
+end
+
+local function image_size(source)
+  local cached = size_cache[source]
+  if cached ~= nil then
+    return cached or nil
+  end
+  if pandoc.image == nil or pandoc.image.size == nil then
+    warn_once(source, "当前 Pandoc 不支持 pandoc.image.size，请升级到 3.1.13 或更高版本")
+    size_cache[source] = false
+    return nil
+  end
+
+  local fetched, _, contents = pcall(pandoc.mediabag.fetch, source)
+  if not fetched or contents == nil then
+    warn_once(source, fetched and "未读取到图片内容" or tostring(_))
+    size_cache[source] = false
+    return nil
+  end
+
+  local measured, size = pcall(pandoc.image.size, contents, PANDOC_WRITER_OPTIONS)
+  if not measured then
+    warn_once(source, tostring(size))
+    size_cache[source] = false
+    return nil
+  end
+
+  size_cache[source] = size
+  return size
+end
+
+local function limit_image(image)
+  if max_width_cm == nil or max_height_cm == nil then
+    return nil
+  end
+  if image.attributes.width ~= nil or image.attributes.height ~= nil then
+    return nil
+  end
+
+  local size = image_size(image.src)
+  if size == nil then
+    return nil
+  end
+
+  local fallback_dpi = PANDOC_WRITER_OPTIONS.dpi or 96
+  local horizontal_dpi = size.dpi_horz > 0 and size.dpi_horz or fallback_dpi
+  local vertical_dpi = size.dpi_vert > 0 and size.dpi_vert or fallback_dpi
+  local width_cm = size.width / horizontal_dpi * 2.54
+  local height_cm = size.height / vertical_dpi * 2.54
+  local scale = math.min(1, max_width_cm / width_cm, max_height_cm / height_cm)
+
+  if scale >= 1 then
+    return nil
+  end
+
+  image.attributes.width = string.format("%.4fcm", width_cm * scale)
+  image.attributes.height = string.format("%.4fcm", height_cm * scale)
+  return image
+end
+
+return {
+  { Meta = read_config },
+  { Image = limit_image },
+}
+`;
+
 // config/lua/add-inline-code.lua
 var add_inline_code_default = `-- Author: Achuan-2
 function Code(el)
@@ -146126,32 +146235,8 @@ function Code(el)
 end
 return { Code = Code }`;
 
-// config/style-config.json
-var style_config_default = `{
-  "$schema": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
-  "schemaVersion": 1,
-  "preset": "default",
-  "options": {
-    "body": {
-      "firstLineIndent": true
-    },
-    "headings": {
-      "1": {
-        "startOnNewPage": false
-      }
-    },
-    "inlineCode": {
-      "background": true
-    },
-    "codeBlock": {
-      "border": true
-    }
-  }
-}
-`;
-
-// config/style.json
-var style_default = `{
+// config/style-raw.json
+var style_raw_default = `{
   "default": {
     "document": {
       "run": {
@@ -147108,10 +147193,33 @@ var style_default = `{
 }
 `;
 
+// config/style-config.json
+var style_config_default = `{
+  "$schema": "https://raw.githubusercontent.com/WXY-V1hZ/md2docx/main/config/style-config.schema.json",
+  "schemaVersion": 1,
+  "options": {
+    "body": {
+      "firstLineIndent": true
+    },
+    "headings": {
+      "1": {
+        "startOnNewPage": false
+      }
+    },
+    "inlineCode": {
+      "background": true
+    },
+    "codeBlock": {
+      "border": true
+    }
+  }
+}
+`;
+
 // src/resources.ts
 var DEFAULT_CONFIG_TEXT = config_default;
 var DEFAULT_STYLE_CONFIG_TEXT = style_config_default;
-var DEFAULT_STYLE_TEXT = style_default;
+var DEFAULT_STYLE_RAW_TEXT = style_raw_default;
 function materializeResource(name2, content3) {
   const directory = join4(TMP_DIR, "resources");
   const path3 = join4(directory, name2);
@@ -147124,41 +147232,30 @@ function materializeResource(name2, content3) {
 function materializeDefaultConfig() {
   return materializeResource("config.json", DEFAULT_CONFIG_TEXT);
 }
-function materializeDefaultStyle() {
-  return materializeResource("style.json", DEFAULT_STYLE_TEXT);
+function materializeDefaultStyleRaw() {
+  return materializeResource("style-raw.json", DEFAULT_STYLE_RAW_TEXT);
 }
 function materializeDefaultStyleConfig() {
-  materializeDefaultStyle();
   return materializeResource("style-config.json", DEFAULT_STYLE_CONFIG_TEXT);
 }
-function materializeLuaFilter() {
+function materializeInlineCodeFilter() {
   return materializeResource("add-inline-code.lua", add_inline_code_default);
 }
-
-// src/style/generate.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync4 } from "node:fs";
-import { writeFile } from "node:fs/promises";
-import { createHash as createHash2 } from "node:crypto";
-import { dirname as dirname4 } from "path";
+function materializeImageSizeFilter() {
+  return materializeResource("limit-image-size.lua", limit_image_size_default);
+}
 
 // src/style/compiler.ts
 import { readFileSync as readFileSync2 } from "node:fs";
 
 // src/style/config.ts
-function isStyleConfig(value2) {
-  if (!isRecord(value2))
-    return false;
-  return "schemaVersion" in value2 || "preset" in value2 || "options" in value2;
-}
 function validateStyleConfig(value2, path3) {
   const root2 = expectRecord2(value2, path3, "样式配置");
-  rejectUnknown(root2, ["$schema", "schemaVersion", "preset", "options"], path3, "样式配置");
+  rejectUnknown(root2, ["$schema", "schemaVersion", "options"], path3, "样式配置");
   if (root2.$schema !== undefined)
     expectString2(root2.$schema, path3, "$schema");
   if (root2.schemaVersion !== 1)
     invalidStyleConfig(path3, "schemaVersion", "目前只支持版本 1");
-  if (root2.preset !== "default")
-    invalidStyleConfig(path3, "preset", '目前只支持 "default"');
   if (root2.options !== undefined)
     validateOptions(root2.options, path3);
   return root2;
@@ -147227,16 +147324,41 @@ function invalidStyleConfig(path3, field, reason) {
 }
 
 // src/style/compiler.ts
-function loadEffectiveStyles(stylePath) {
-  const source = parseJson(readFileSync2(stylePath, "utf-8"), stylePath);
-  if (!isStyleConfig(source))
-    return expectStyleDefinition(source, stylePath);
-  const config = validateStyleConfig(source, stylePath);
-  const preset = expectStyleDefinition(parseJson(DEFAULT_STYLE_TEXT, "内置默认样式"), "内置默认样式");
-  return compileStyleConfig(preset, config);
-}
-function compileStyleConfig(preset, config) {
-  const styles = structuredClone(preset);
+function resolveEffectiveStyles(sources, defaults) {
+  const rawPath = sources.styleRawPath ?? defaults?.styleRawPath ?? materializeDefaultStyleRaw();
+  const rawStyle = loadStyleRaw(rawPath);
+  if (sources.styleConfigPath) {
+    return compileStyleConfig(rawStyle, loadStyleConfig(sources.styleConfigPath));
+  }
+  if (sources.styleRawPath)
+    return rawStyle;
+  const defaultConfigPath = defaults?.styleConfigPath ?? materializeDefaultStyleConfig();
+  return compileStyleConfig(rawStyle, loadStyleConfig(defaultConfigPath));
+}
+function loadStyleRaw(path3) {
+  const source = parseJson(readFileSync2(path3, "utf-8"), path3, "底层样式文件");
+  if (!isRecord2(source))
+    throw new Error(`底层样式文件必须是 JSON 对象：${path3}`);
+  if (looksLikeStyleConfig(source)) {
+    throw new Error(`底层样式文件无效：${path3}
+当前文件看起来是语义化样式配置，请改用 --style-config`);
+  }
+  if (!looksLikeRawStyle(source)) {
+    throw new Error(`底层样式文件无效：${path3}
+缺少 Word 样式定义`);
+  }
+  return source;
+}
+function loadStyleConfig(path3) {
+  const source = parseJson(readFileSync2(path3, "utf-8"), path3, "语义化样式配置");
+  if (isRecord2(source) && looksLikeRawStyle(source)) {
+    throw new Error(`语义化样式配置无效：${path3}
+当前文件看起来是底层样式，请改用 --style-raw`);
+  }
+  return validateStyleConfig(source, path3);
+}
+function compileStyleConfig(rawStyle, config) {
+  const styles = structuredClone(rawStyle);
   const options = config.options;
   if (!options)
     return styles;
@@ -147297,12 +147419,12 @@ function applyCodeBlockBorder(styles, enabled) {
 function findStyle(styles, collectionName, name2) {
   const collection = styles[collectionName];
   if (!Array.isArray(collection)) {
-    throw new Error(`内置样式缺少 ${collectionName}，无法应用样式配置`);
+    throw new Error(`底层样式缺少 ${collectionName}，无法应用语义化样式配置`);
   }
   const normalizedName = name2.toLowerCase();
   const style = collection.find((entry) => isRecord2(entry) && typeof entry.name === "string" && entry.name.toLowerCase() === normalizedName);
   if (!style)
-    throw new Error(`内置样式缺少“${name2}”，无法应用样式配置`);
+    throw new Error(`底层样式缺少“${name2}”，无法应用语义化样式配置`);
   return style;
 }
 function ensureObject(parent, key) {
@@ -147316,25 +147438,30 @@ function ensureObject(parent, key) {
 function optionalObject(value2) {
   return isRecord2(value2) ? value2 : {};
 }
-function parseJson(text5, path3) {
+function parseJson(text5, path3, kind) {
   try {
     return JSON.parse(text5);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`样式文件不是有效的 JSON：${path3}
+    throw new Error(`${kind}不是有效的 JSON：${path3}
 ${message}`);
   }
 }
-function expectStyleDefinition(value2, path3) {
-  if (!isRecord2(value2))
-    throw new Error(`样式文件必须是 JSON 对象：${path3}`);
-  return value2;
+function looksLikeStyleConfig(value2) {
+  return "schemaVersion" in value2 || "options" in value2 || "preset" in value2;
+}
+function looksLikeRawStyle(value2) {
+  return ["default", "paragraphStyles", "characterStyles", "tableStyles", "tableStylesXml"].some((key) => (key in value2));
 }
 function isRecord2(value2) {
   return typeof value2 === "object" && value2 !== null && !Array.isArray(value2);
 }
 
 // src/style/generate.ts
+import { existsSync as existsSync5, mkdirSync as mkdirSync4 } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { createHash as createHash2 } from "node:crypto";
+import { dirname as dirname4 } from "path";
 async function generateTemplateDocxFromStyles(raw, outputPath) {
   const { Document: Document2, Packer: Packer3 } = await Promise.resolve().then(() => (init_dist(), exports_dist));
   const tableStylesXml = raw.tableStylesXml;
@@ -147361,14 +147488,16 @@ async function generateTemplateDocxFromStyles(raw, outputPath) {
   await writeFile(outputPath, buf);
 }
 var generatePromises = new Map;
-async function ensureTemplateDocx(styleJsonPath) {
-  const styles = loadEffectiveStyles(styleJsonPath);
-  const hash = createHash2("sha256").update(JSON.stringify(styles)).digest("hex").slice(0, 16);
+function styleCacheHash(rawStyle) {
+  return createHash2("sha256").update(JSON.stringify(rawStyle)).digest("hex").slice(0, 16);
+}
+async function ensureTemplateDocx(rawStyle) {
+  const hash = styleCacheHash(rawStyle);
   const outputPath = styleTemplateDocx(hash);
   if (!existsSync5(outputPath)) {
     let promise = generatePromises.get(outputPath);
     if (!promise) {
-      promise = generateTemplateDocxFromStyles(styles, outputPath).catch((error) => {
+      promise = generateTemplateDocxFromStyles(rawStyle, outputPath).catch((error) => {
         generatePromises.delete(outputPath);
         throw error;
       });
@@ -147385,25 +147514,29 @@ async function convertMarkdown(options) {
     throw new Error("缺少必填参数：--file");
   const input = resolveInputPath(options.file, [".md", ".markdown"], "Markdown 文件");
   const configPath = options.config ? resolveInputPath(options.config, [".json"], "配置文件") : materializeDefaultConfig();
-  const stylePath = options.style ? resolveInputPath(options.style, [".json"], "样式文件") : materializeDefaultStyleConfig();
+  const styleRawPath = options.styleRaw ? resolveInputPath(options.styleRaw, [".json"], "底层样式文件") : undefined;
+  const styleConfigPath = options.styleConfig ? resolveInputPath(options.styleConfig, [".json"], "语义化样式配置") : undefined;
   const baseName = parse4(input).name;
   const output = resolveOutputPath(options.output, `${baseName}.docx`, [".docx"], "DOCX 输出文件");
-  prepareOutput(output, options.force ?? false);
+  prepareOutput(output);
   const config = await loadConfig(configPath);
   const outDir = preprocessDir(input);
   mkdirSync5(outDir, { recursive: true });
   const formatted = await preprocess2(input, config, outDir);
   const markdownOutput = formattedMdPath(input);
   writeFileSync3(markdownOutput, formatted, "utf-8");
-  const templatePath = await ensureTemplateDocx(stylePath);
-  const luaFilter = materializeLuaFilter();
+  const effectiveStyles = resolveEffectiveStyles({ styleRawPath, styleConfigPath });
+  const templatePath = await ensureTemplateDocx(effectiveStyles);
+  const inlineCodeFilter = materializeInlineCodeFilter();
+  const imageSizeArgs = config.imageSize.enabled ? buildImageSizePandocArgs(config.imageSize, materializeImageSizeFilter()) : [];
   const pandocArgs = [
     markdownOutput,
     "-o",
     output,
     ...buildPandocResourcePathArgs(input),
     `--reference-doc=${templatePath}`,
-    ...existsSync6(luaFilter) ? [`--lua-filter=${luaFilter}`] : []
+    ...existsSync6(inlineCodeFilter) ? [`--lua-filter=${inlineCodeFilter}`] : [],
+    ...imageSizeArgs
   ];
   const { exitCode, stderr } = await runProcess("pandoc", pandocArgs);
   if (exitCode !== 0) {
@@ -147411,6 +147544,15 @@ async function convertMarkdown(options) {
   }
   console.log(`已生成：${output}`);
 }
+function buildImageSizePandocArgs(config, filterPath) {
+  if (!config.enabled)
+    return [];
+  return [
+    `--metadata=md2docx-image-max-width-cm:${config.maxWidthCm}`,
+    `--metadata=md2docx-image-max-height-cm:${config.maxHeightCm}`,
+    `--lua-filter=${filterPath}`
+  ];
+}
 function buildPandocResourcePathArgs(inputPath, workingDirectory = process.cwd()) {
   const workingDir = resolve5(workingDirectory);
   const sourceDir = dirname5(resolve5(inputPath));
@@ -148054,23 +148196,32 @@ function extractStylesFromDocx(docxPath) {
 // src/commands/export.ts
 async function exportConfig(options) {
   const output = resolveOutputPath(options.output, "config.json", [".json"], "配置输出文件");
-  prepareOutput(output, options.force ?? false);
+  prepareOutput(output);
   writeFileSync4(output, DEFAULT_CONFIG_TEXT, "utf-8");
   console.log(`已导出配置：${output}`);
 }
-async function exportStyle(options) {
+async function exportStyleRaw(options) {
   const source = options.file ? resolveInputPath(options.file, [".docx"], "DOCX 文件") : undefined;
-  const defaultName = source ? `${parse5(source).name}_style.json` : "style.json";
-  const output = resolveOutputPath(options.output, defaultName, [".json"], "样式输出文件");
-  prepareOutput(output, options.force ?? false);
+  const defaultName = defaultStyleRawOutputName(source);
+  const output = resolveOutputPath(options.output, defaultName, [".json"], "底层样式输出文件");
+  prepareOutput(output);
   if (source) {
     const styles = extractStylesFromDocx(source);
     writeFileSync4(output, `${JSON.stringify(styles, null, 2)}
 `, "utf-8");
   } else {
-    writeFileSync4(output, DEFAULT_STYLE_TEXT, "utf-8");
+    writeFileSync4(output, DEFAULT_STYLE_RAW_TEXT, "utf-8");
   }
-  console.log(`已导出样式：${output}`);
+  console.log(`已导出底层样式：${output}`);
+}
+function defaultStyleRawOutputName(source) {
+  return source ? `${parse5(source).name}_style-raw.json` : "style-raw.json";
+}
+async function exportStyleConfig(options) {
+  const output = resolveOutputPath(options.output, "style-config.json", [".json"], "语义化样式配置输出文件");
+  prepareOutput(output);
+  writeFileSync4(output, DEFAULT_STYLE_CONFIG_TEXT, "utf-8");
+  console.log(`已导出语义化样式配置：${output}`);
 }
 
 // src/commands/format.ts
@@ -148081,17 +148232,12 @@ async function formatMarkdown(options) {
   const configPath = options.config ? resolveInputPath(options.config, [".json"], "配置文件") : materializeDefaultConfig();
   const defaultName = `${parse6(input).name}_formatted.md`;
   const output = resolveOutputPath(options.output, defaultName, [".md", ".markdown"], "Markdown 输出文件");
-  const force = options.force ?? false;
-  prepareOutput(output, force);
+  prepareOutput(output);
   const config = await loadConfig(configPath);
   const outputName = parse6(output).name;
   const assetsName = `${outputName}_assets`;
   const assetsDir = resolve6(dirname6(output), assetsName);
   if (config.renderMermaid.enabled && existsSync7(assetsDir)) {
-    if (!force) {
-      throw new Error(`资源目录已存在：${assetsDir}
-使用 --force 覆盖现有目录`);
-    }
     const parent = resolve6(dirname6(output));
     if (dirname6(assetsDir) !== parent)
       throw new Error(`拒绝清理非输出目录：${assetsDir}`);
@@ -148108,7 +148254,8 @@ async function run(args) {
     convert: convertMarkdown,
     format: formatMarkdown,
     exportConfig,
-    exportStyle,
+    exportStyleRaw,
+    exportStyleConfig,
     clean: cleanIntermediateFiles
   });
   program2.exitOverride();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@v1hz/md2docx",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "基于 pandoc 的 Markdown 转 Word 工具，自动格式化 Markdown，支持自定义样式，AI 友好，用户友好。",
   "keywords": [
     "converter",