@v1hz/md2docx 2.5.0 → 2.7.0

package/README.md

@@ -17,431 +17,221 @@
 
 ## 功能
 
-| 功能              | 说明                                                             |
-| ----------------- | ---------------------------------------------------------------- |
-| 文档标题          | 从 YAML frontmatter、H1 或文件名提取标题                         |
-| 标题层级归一化    | 将最浅标题归一化为 H1，并修复标题层级跳跃                        |
-| 标题编号          | 生成 `1`、`1.1`、`1.1.1` 等编号，并可剥离常见的已有中英文编号    |
-| 表格与图片编号    | 自动生成“表 1”“图 1：标题”等题注                                 |
-| 图片尺寸限制      | 按自然尺寸等比缩小超过最大宽度或高度的图片                       |
-| Mermaid 图表      | 使用 beautiful-mermaid 和 resvg-wasm 将 Mermaid 渲染为高 DPI PNG |
-| Word 样式         | 支持受控语义化配置和完整底层样式，也可从现有 DOCX 提取样式       |
-| Markdown 格式化   | 可只运行预处理流水线，输出格式化后的 Markdown                    |
-| 去除分隔符        | 默认移除 `---`、`***`、`___` 等分隔符行，减少无用页面间距        |
-| 集中缓存          | 中间文件统一存储到 `~/.md2docx/`，不会在当前目录创建 `tmp/`      |
-| Node 与可执行版本 | 支持 npm CLI，也支持构建不依赖 Node.js/Bun 的 Windows 可执行文件 |
+- **文档标题** — 从 YAML frontmatter、H1 或文件名提取
+- **标题归一化** — 最浅标题 → H1，修复层级跳跃
+- **标题编号** — `1`、`1.1`、`1.1.1`，可剥离已有中英文编号
+- **表格与图片题注** — "表 1"、"图 1：标题"
+- **图片尺寸限制** — 等比缩小超限图片
+- **Mermaid 渲染** — beautiful-mermaid + resvg-wasm → 高 DPI PNG
+- **Word 样式** — 受控语义化配置 / 完整底层样式 / 从 DOCX 提取
+- **预设系统** — 可切换、可继承默认值的配置与样式预设
+- **Markdown 格式化** — 只运行预处理流水线
+- **集中缓存** — `~/.md2docx/`，工作目录保持干净
+- **双构建** — npm CLI + Windows 单文件 EXE
 
-## 安装方式
+---
 
-### npm CLI
+## 桌面应用
 
-前置依赖：
+仓库包含基于 Electron + Vue 3 + Vite + Tailwind CSS 的桌面端（早期开发阶段）。应用图标以立体 Markdown 卡片、转换箭头和 Word 文档构成，在标题栏小尺寸与桌面大图标下保持一致识别。标题栏使用 `titleBarStyle: "hidden"` 自定义内容区域并在各平台保留原生窗口控制按钮。系统拖入的文件通过 preload 中的 `webUtils.getPathForFile()` 解析本地路径。桌面转换复用完整 CLI 流水线与预设，支持源文件目录、指定文件夹或每次询问三种输出位置，以及覆盖、自动重命名或每次询问三种同名文件策略。成功文件会从队列收入标题栏转换记录；点击记录按钮后，每个文件都可独立打开、定位或重新加入文件列表，之后按当前转换设置再次转换。设置以居中模态窗口展示，可检测 Pandoc，并通过可视化编辑器调整转换规则、图片与图表行为和语义化 Word 样式；打开时弹窗以短暂的淡入、上移动画进入，标题栏设置按钮同时显示蓝色激活状态，并遵守系统的“减少动态效果”偏好。内置 `default` 只读，自定义时保存为新的用户预设，用户预设可直接编辑。设置中的选择器使用应用内统一菜单，支持鼠标和完整键盘操作，不依赖平台原生网页下拉样式。Windows 安装版启动后会静默检查 GitHub Release 更新；发现版本时显示非阻塞通知条，下载期间可继续工作，完成后由用户选择重新启动。设置页也可手动检查；便携版不会尝试自动安装。复制、重命名和删除位于更多菜单，未保存的编辑在离开前会确认。偏好与记录仅保存在本机。旧版扁平桌面设置会继续生效，并在下次保存时迁移到共享格式。转换记录最多保留 30 条；`Ctrl/⌘ + Enter` 可直接开始转换。
 
-- [Node.js 22.12+](https://nodejs.org/)
-- [Pandoc](https://pandoc.org/installing.html)，并确保 `pandoc` 可通过 `PATH` 调用；图片尺寸限制需要 Pandoc 3.1.13+
+主界面右侧始终提供转换设置侧边栏，即使文件列表为空也可提前调整。它与预设编辑器使用同一套字段和视觉样式；选择预设会重置侧边栏并同步默认预设，随后直接调整只影响桌面转换，不会改写预设。主界面右上角的固定侧边栏按钮或 `Ctrl+Alt+B` 可显示/隐藏它；按钮不会随侧边栏展开移动，设置与显示状态会自动保存在本机，并作为配置快照应用于下一批文件。开发模式为每次 `bun run dev` 使用独立的 Chromium 会话缓存，避免残留开发实例争用缓存目录。
 
-```bash
-npm install -g @v1hz/md2docx
-md2docx --version
-md2docx report.md
-```
-
-也可以不全局安装：
+主界面右上角另有纯图标编辑按钮，可在文件列表与 Markdown 文本编辑器之间切换。用户可直接粘贴文本、设置文档名称并使用当前侧边栏配置转换；文本由主进程安全物化为应用私有目录中的临时 Markdown 文件，再进入与文件转换相同的完整流水线。编辑按钮属于文件工作区，会在侧边栏展开时随工作区边缘左移，而侧边栏按钮保持固定。输出位置设置为“源文件目录”时，文本编辑器转换会弹出 DOCX 保存位置选择；从转换记录重新加入源文件时会自动返回文件列表。
 
 ```bash
-npx @v1hz/md2docx report.md
+bun run build:electron # 构建主进程与 preload
+bun run electron       # 构建 Electron 与前端并启动
+bun run dev            # 启动前端开发服务器与 Electron
+bun run pack           # 构建支持自动更新的 Windows 安装版
+bun run pack:portable  # 构建不自动安装更新的便携版
 ```
 
-## 快速开始
+开发模式会自动显示一次更新通知预览；关闭后可在设置底部点“预览更新”再次查看。预览下载仅模拟进度，不访问更新服务器，也不会退出或安装。
 
-```bash
-# 只有输入路径时，可以省略 --file
-md2docx report.md
+## AI 辅助
 
-# 使用任何转换选项时，输入必须通过 --file 指定
-md2docx --file report.md --output output/report.docx
+[`SKILL.md`](SKILL.md) 供 AI 代码助手引用，使其正确使用 md2docx CLI。
 
-# 使用自定义配置、底层样式和语义化样式配置
-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-raw
-md2docx export style-config
+前置：Node.js 22.12+, [Pandoc](https://pandoc.org/installing.html)（需在 PATH 中；图片尺寸限制需 Pandoc 3.1.13+）
 
-# 从现有 DOCX 提取样式
-md2docx export style-raw -f template.docx
+```bash
+npm install -g @v1hz/md2docx
+# 或
+npx @v1hz/md2docx report.md
+```
 
-# 删除 ~/.md2docx 中的中间文件和缓存
-md2docx clean
+## 快速开始
+
+```bash
+md2docx report.md                     # 仅路径
+md2docx -f report.md -o output.docx   # 带选项（必须有 --file）
+md2docx -f report.md -c config.json --style-raw raw.json --style-config style-config.json
+md2docx preset save --name academic --config config.json
+md2docx preset use academic
+md2docx format -f report.md           # 只格式化
+md2docx export config                 # 导出配置
+md2docx export style-raw -f template.docx  # 从 DOCX 提取样式
+md2docx clean                         # 清除缓存
 ```
 
 所有写文件命令默认覆盖已有输出。
 
+---
+
 ## CLI 参考
 
-```shell
+```text
 md2docx <markdown>
 md2docx -f <markdown> [转换选项]
 md2docx format -f <markdown> [选项]
-md2docx export config [选项]
-md2docx export style-raw [选项]
-md2docx export style-config [选项]
+md2docx export config|style-raw|style-config [选项]
+md2docx preset list|use <name>|save --name <name> [选项]
 md2docx clean
 ```
 
-### 转换
+### 转换选项
 
-| 参数                    | 说明                                     |
-| ----------------------- | ---------------------------------------- |
-| `<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`         | 显示版本号                               |
+| 参数                    | 说明                         |
+| ----------------------- | ---------------------------- |
+| `<markdown>`            | 位置参数，仅无其他选项时可用 |
+| `-f, --file <path>`     | Markdown 输入                |
+| `--preset <name>`       | 本次指定预设                 |
+| `-c, --config <path>`   | 配置 JSON                    |
+| `--style-raw <path>`    | 底层 Word 样式 JSON          |
+| `--style-config <path>` | 语义化样式配置 JSON          |
+| `-o, --output <path>`   | DOCX 输出                    |
 
-位置参数不能和 `--file`、`--config`、`--style-raw`、`--style-config` 或 `--output` 混用。例如：
-
-```bash
-md2docx report.md                 # 正确
-md2docx report.md -o report.docx  # 错误
-md2docx -f report.md -o report.docx # 正确
-```
+位置参数不能与 `--file` 或其他选项混用。`format --file` 必填，支持 `--preset`/`--config`/`--output`，不接受样式参数，不调用 Pandoc。
 
-### format
-
-`format` 运行完整 Markdown 预处理，但不生成 DOCX，也不调用 Pandoc。
-
-| 参数                  | 说明                                        |
-| --------------------- | ------------------------------------------- |
-| `-f, --file <path>`   | 必填，Markdown 输入文件                     |
-| `-c, --config <path>` | 自定义配置 JSON                             |
-| `-o, --output <path>` | 输出 Markdown，默认 `<文件名>_formatted.md` |
-
-### export
-
-```bash
-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` 导出内置 Markdown 处理配置。`export style-raw` 不带 `--file` 时导出内置底层 Word 样式；指定 DOCX 时从该文档提取底层样式。`export style-config` 导出默认语义化样式配置。
-
-### clean
-
-```bash
-md2docx clean
-```
-
-`clean` 只允许删除当前用户主目录下严格匹配的 `~/.md2docx/`。如果目标是符号链接，只删除链接本身。命令可重复执行；目录不存在时正常退出。
-
-npm 卸载不会可靠地清理用户数据。卸载前如需清理，请显式运行：
-
-```bash
-md2docx clean
-npm uninstall -g @v1hz/md2docx
-```
-
-## 默认输出
+### 默认输出
 
 ```text
-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-raw                  → ./style-raw.json
-md2docx export style-raw -f template.docx → ./template_style-raw.json
-md2docx export style-config               → ./style-config.json
+report.md                     → ./report.docx
+format -f report.md           → ./report_formatted.md
+export config                 → ./config.json
+export style-raw              → ./style-raw.json
+export style-raw -f t.docx    → ./t_style-raw.json
+export style-config           → ./style-config.json
 ```
 
-## 中间文件与缓存
+---
 
-所有运行时资源统一位于：
+## 中间文件
 
-```text
+```
 ~/.md2docx/
-├── preprocess/
-│   └── <输入文件名>-<绝对路径哈希>/
-│       ├── <输入文件名>_formatted.md
-│       └── mermaid_*.png
-├── resources/
-│   ├── config.json
-│   ├── style-config.json
-│   ├── style-raw.json
-│   ├── add-inline-code.lua
-│   └── limit-image-size.lua
-└── style/
-    └── <样式内容哈希>.docx
+├── settings.json + presets/          # 持久数据，clean 保留
+├── preprocess/<basename>-<hash:12>/  # 预处理 Markdown + Mermaid PNG
+├── resources/default/*.json + *.lua  # 物化的内置资源
+└── style/<hash:16>.docx              # reference DOCX 缓存
 ```
 
-输入文件的绝对路径参与目录哈希，因此不同目录下的同名 Markdown 不会复用中间文件。内置资源会在需要时写入 `resources/`；样式模板按样式内容哈希缓存。
-
-输出 DOCX 和显式导出的配置、样式仍写到用户指定位置或当前工作目录，不会写入缓存目录。
+预处理目录用输入绝对路径 SHA-256 前 12 位，不同目录的同名文件隔离。Pandoc 读取缓存 Markdown 时以原始 Markdown 目录为优先资源搜索路径。
 
-虽然 Pandoc 实际读取的是缓存中的格式化 Markdown，但本地相对资源始终优先相对于**原始 Markdown 所在目录**解析；找不到时再搜索命令运行目录。例如 `C:/docs/example.md` 中的 `./pictures/test.png` 会解析为 `C:/docs/pictures/test.png`，与从哪个目录执行 `md2docx` 无关。绝对路径、HTTP(S) URL 和 Mermaid 生成的缓存图片不受影响。
+---
 
 ## 配置
 
-内置配置来自 `config/config.json`，并由 `config/config.schema.json` 提供 JSON Schema。推荐先导出再编辑：
+内置配置来自 `config/default/config.json`（`config/config.schema.json` 提供校验）。推荐先导出再编辑：
 
 ```bash
 md2docx export config
 md2docx -f report.md -c config.json
 ```
 
-CLI 不支持覆盖单个配置项，所有配置都通过 JSON 文件管理。
-
-| 配置项                           | 说明                                           | 默认值                |
-| -------------------------------- | ---------------------------------------------- | --------------------- |
-| `detectTitle.enabled`            | 自动设置文档标题                               | `true`                |
-| `detectTitle.strategy`           | `first-h1` / `single-h1` / `filename` / `none` | `"first-h1"`          |
-| `normalizeHeadings.enabled`      | 修正标题起始层级与层级跳跃                     | `true`                |
-| `numberHeadings.enabled`         | 为标题添加多级编号                             | `true`                |
-| `numberHeadings.detectExisting`  | 重新编号前移除已识别的编号                     | `true`                |
-| `numberHeadings.useBuiltinRules` | 使用内置中文和数字编号识别规则                 | `true`                |
-| `figureCaption.enabled`          | 为独立图片添加题注                             | `true`                |
-| `figureCaption.format`           | 图片编号格式                                   | `"图 {n}"`            |
-| `figureCaption.separator`        | 图片编号与标题之间的分隔符                     | `"："`                |
-| `tableCaption.enabled`           | 为表格添加题注                                 | `true`                |
-| `tableCaption.format`            | 表格编号格式                                   | `"表 {n}"`            |
-| `tableCaption.separator`         | 表格编号与标题之间的分隔符                     | `" "`                 |
-| `renderMermaid.enabled`          | 将 Mermaid 渲染为 PNG                          | `true`                |
-| `renderMermaid.theme`            | beautiful-mermaid 主题                         | `"tokyo-night-light"` |
-| `renderMermaid.density`          | PNG 输出 DPI，最小值 72                        | `200`                 |
-| `imageSize.enabled`              | 等比缩小超过尺寸限制的图片                     | `true`                |
-| `imageSize.maxWidthCm`           | DOCX 图片最大宽度（厘米）                      | `12`                  |
-| `imageSize.maxHeightCm`          | DOCX 图片最大高度（厘米）                      | `12`                  |
-| `removeThematicBreaks.enabled`   | 移除 `---`、`***`、`___` 等分隔符行            | `true`                |
-
-图片尺寸限制在 Pandoc 生成 DOCX 前通过 Lua filter 应用。程序读取图片像素尺寸和 DPI，仅缩小超限图片，不会放大小图；宽度和高度使用同一缩放比例。Markdown 中已经显式设置 `width` 或 `height` 的图片视为用户覆盖，不应用全局限制。单张图片无法读取尺寸时会输出警告并继续转换。
+| 配置项                                                    | 说明                                            | 默认值                                 |
+| --------------------------------------------------------- | ----------------------------------------------- | -------------------------------------- |
+| `detectTitle.enabled / strategy`                          | 自动设置标题 / first-h1/single-h1/filename/none | `true` / `"first-h1"`                  |
+| `normalizeHeadings.enabled`                               | 修正标题层级                                    | `true`                                 |
+| `numberHeadings.{enabled,detectExisting,useBuiltinRules}` | 标题编号 / 剥离已有编号                         | `true` / `true` / `true`               |
+| `figureCaption.{enabled,format,separator}`                | 图片题注 / `"图 {n}"` / `"："`                  | `true`                                 |
+| `tableCaption.{enabled,format,separator}`                 | 表格题注 / `"表 {n}"` / `" "`                   | `true`                                 |
+| `renderMermaid.{enabled,theme,density}`                   | Mermaid 渲染 / 主题 / DPI（≥72）                | `true` / `"tokyo-night-light"` / `200` |
+| `imageSize.{enabled,maxWidthCm,maxHeightCm}`              | 图片尺寸限制（厘米）                            | `true` / `12` / `12`                   |
+| `removeThematicBreaks.enabled`                            | 移除分隔符行                                    | `true`                                 |
 
-## 样式定制
+图片尺寸通过 Lua filter 在 Pandoc 阶段等比缩小，不放大小图。Markdown 已显式设 width/height 时不应用。单图读取失败时警告并继续。
 
-普通用户推荐使用受控的语义化样式配置，只修改程序明确开放的高频选项。其余颜色、尺寸、对齐方式、间距和 Word 样式继承关系继续由内置预设管理。
-
-仓库中的 `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,
-  "options": {
-    "body": {
-      "firstLineIndent": false,
-      "lineSpacing": "onePointFive"
-    },
-    "headings": {
-      "1": {
-        "startOnNewPage": false,
-        "alignment": "left",
-        "bold": true
-      },
-      "2": {
-        "bold": true
-      },
-      "3": {
-        "bold": true
-      },
-      "4": {
-        "bold": true,
-        "italic": false
-      },
-      "5": {
-        "bold": true,
-        "italic": false
-      },
-      "6": {
-        "bold": true,
-        "italic": false
-      }
-    },
-    "inlineCode": {
-      "background": false
-    },
-    "codeBlock": {
-      "border": false
-    }
-  }
-}
-```
-
-将配置保存为 `style-config.json` 后使用：
-
-```bash
-md2docx -f report.md --style-config style-config.json
-```
+---
 
-字段缺失表示继承底层样式；`true` 表示显式启用完整效果；`false` 表示显式关闭。正文行距为浮点数倍数，例如 `1.5` 表示 1.5 倍行距；一级标题对齐只接受 `left`、`center`。当前还开放一至六级标题粗体，以及四至六级标题斜体。完整设计见 [`docs/style-config-design.md`](docs/style-config-design.md)。
+## 样式定制
 
-转换时按以下规则选择输入：
+受控语义化配置（`config/default/style-config.json`）开放以下白名单选项：
 
-| 参数                | 行为                                |
-| ------------------- | ----------------------------------- |
-| 都不指定            | 默认 raw + 默认 config              |
-| 仅 `--style-raw`    | 直接使用用户 raw，不应用默认 config |
-| 仅 `--style-config` | 用户 config 应用到默认 raw          |
-| 两者都指定          | 用户 config 应用到用户 raw          |
+- `body.firstLineIndent` — 正文首行缩进
+- `body.lineSpacing` — 行距倍数（如 `1.5`）
+- `headings["1"]` — `startOnNewPage`、`alignment`（left/center）、`bold`
+- `headings["2".."6"]` — `bold`
+- `headings["4".."6"]` — `italic`
+- `inlineCode.background` — 行内代码背景
+- `codeBlock.border` — 代码块外框
 
-最终有效的底层样式用于生成 reference DOCX，并通过 Pandoc 的 `--reference-doc` 应用。`--style-raw` 和 `--style-config` 类型固定，不能互换。
+字段缺失继承底层样式；`true` 写入完整效果；`false` 写入 Word 关闭值。输入组合规则：
 
-### 从现有 DOCX 提取
+| 参数                | 行为                          |
+| ------------------- | ----------------------------- |
+| 都不指定            | 当前预设 raw + config         |
+| 仅 `--style-raw`    | 直接使用 raw，不读默认 config |
+| 仅 `--style-config` | config 应用到当前预设 raw     |
+| 两者都指定          | config 应用到用户 raw         |
 
 ```bash
+md2docx export style-config
+md2docx -f report.md --style-config style-config.json
+# 从现有 DOCX 提取样式
 md2docx export style-raw -f template.docx
 md2docx -f report.md --style-raw template_style-raw.json
 ```
 
-### 高级手动维护
-
-主要区域包括：
-
-- `default.document`：全局字体、字号与段落设置
-- `default.heading1` 至 `default.heading6`：标题样式
-- `default.title`：文档标题样式
-- `paragraphStyles`：自定义段落样式
-- `characterStyles`：自定义字符样式
-- `tableStylesXml`：从 DOCX 提取并重新注入的表格样式 XML
-
-基于 `a0`（Body Text）的样式会继承首行缩进。如果子样式不需要缩进，应在 `indent` 中显式清零。
-
-## Mermaid 渲染
-
-渲染流程如下：
-
-```text
-Mermaid
-→ beautiful-mermaid
-→ SVG
-→ 内联 CSS var() / color-mix()
-→ @resvg/resvg-wasm
-→ 写入正确的 PNG DPI 元数据
-→ PNG
-```
-
-resvg 不直接支持 beautiful-mermaid 输出中的所有 CSS 自定义属性，因此转换前会解析：
-
-- `var(--name)`
-- `var(--name, fallback)`
-- 嵌套 fallback
-- `color-mix(in srgb, ...)`
-- 三位和六位十六进制颜色
+完整设计见 [`docs/style-config-design.md`](docs/style-config-design.md)。
 
-Windows 会显式加载微软雅黑、Arial 和 Consolas；macOS 与 Linux 使用各自的候选系统字体。PNG 像素尺寸和 `pHYs` DPI 元数据都与 `renderMermaid.density` 保持一致。
-
-运行时不依赖 Sharp。Sharp 只作为开发依赖，用于测试中比较 resvg 与旧渲染结果，不会打入 npm 运行时包或平台 EXE。
+---
 
 ## 处理流水线
 
-```text
-Markdown
-    ↓
-解析 AST
-    ↓
-addTitle()
-    ↓
-removeThematicBreaks()
-    ↓
-normalizeHeadings()
-    ↓
-numberHeadings()
-    ↓
-numberTables()
-    ↓
-renderMermaid()
-    ↓
-numberPictures()
-    ↓
-序列化 Markdown
-    ↓
-生成或复用 reference DOCX
-    ↓
-Pandoc + 行内代码/图片尺寸 Lua filter
-    ↓
-DOCX
 ```
+Markdown → AST → addTitle → removeThematicBreaks → normalizeHeadings
+→ numberHeadings → numberTables → renderMermaid → numberPictures
+→ 序列化 → reference DOCX → Pandoc + Lua filter → DOCX
+```
+
+`removeThematicBreaks` 在标题处理之前；`numberTables` 在 Mermaid 渲染之前；`renderMermaid` 在 `numberPictures` 之前。
 
-`removeThematicBreaks()` 在标题处理之前执行，避免分隔符干扰文档结构。
-`numberTables()` 必须先于 Mermaid 渲染；`numberPictures()` 必须后于 Mermaid 渲染，这样 Mermaid 生成的图片也能获得图题。
+---
 
 ## 构建
 
-从源码开发需要 [Bun](https://bun.sh/)。
+需要 [Bun](https://bun.sh/)。
 
 ```bash
-git clone https://github.com/WXY-V1hZ/md2docx.git
-cd md2docx
+git clone https://github.com/WXY-V1hZ/md2docx.git && cd md2docx
 bun install
 
-# 从源码运行
-bun run src/index.ts report.md
+bun run src/index.ts report.md   # 从源码运行
+bun test                          # 全部测试
+bun check                         # tsc + oxlint + oxfmt
 
-# 测试和静态检查
-bun test
-bun check
+bun run build                     # npm 构建 → dist/index.js + WASM
+bun run build:exe                 # Windows 单文件 → dist/md2docx.exe
 ```
 
-### npm 构建
+两种构建互斥（先 `clean:dist`）。`prepack` 自动执行 `bun run build`。
 
-```bash
-bun run build
-```
-
-输出：
-
-```text
-dist/
-├── index.js
-└── index_bg.wasm
-```
-
-依赖会打包进 `index.js`，resvg WASM 作为相邻资源输出。`prepack` 会自动执行此构建。
-
-### Windows 可执行文件
-
-```bash
-bun run build:exe
-```
-
-Windows 输出为 `dist/md2docx.exe`。
-
-`build` 和 `build:exe` 都会先删除整个 `dist/`，因此两种产物不会同时保留。尤其不要依赖手工生成的 EXE 参与 `npm publish`：发布时 `prepack` 会重新生成 npm 所需的 `index.js` 和 WASM。
+---
 
 ## 常见问题
 
-### 找不到 Pandoc
-
-先检查：
-
-```bash
-pandoc --version
-```
-
-如果命令不存在，请从 [Pandoc 官方安装页](https://pandoc.org/installing.html) 安装，并重新打开终端使 `PATH` 生效。
-
-### 从其他目录转换时图片缺失
+**找不到 Pandoc** — 确认 `pandoc --version` 可用，从 [pandoc.org](https://pandoc.org/installing.html) 安装并重启终端。
 
-相对图片路径应以原始 Markdown 文件为基准：
+**跨目录转换图片缺失** — 相对路径以原始 Markdown 文件为基准解析，顺序优先于调用目录。检查路径大小写、文件存在性和 URL 编码。
 
-```text
-docs/
-├── example.md
-└── pictures/
-    └── test.png
-```
-
-```markdown
-![](./pictures/test.png)
-```
-
-新版会把原始文档目录和命令运行目录传给 Pandoc 的 `--resource-path`，并优先搜索原始文档目录。如果仍然缺图，请检查路径大小写、文件是否存在，以及图片语法中是否包含错误的 URL 编码。
+---
 
 ## 许可
 
-md2docx 以 [GNU GPL v3.0](LICENSE) 发布。
+[GNU GPL v3.0](LICENSE)