sdpy-kit 0.6.3__tar.gz → 0.6.4__tar.gz

{sdpy_kit-0.6.3 → sdpy_kit-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.3
+Version: 0.6.4
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -98,7 +98,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
 | `kit.docs.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
-| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML | `md2doc` |
+| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML（含图片） | `md2doc` |
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
 | `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
@@ -125,7 +125,7 @@ uv add sdpy-kit
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
 | `ai` | AI 服务池（httpx + python-dotenv） | `pip install "sdpy-kit[ai]"` |
-| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2） | `pip install "sdpy-kit[md2doc]"` |
+| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2，含图片） | `pip install "sdpy-kit[md2doc]"` |
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
@@ -1076,12 +1076,18 @@ Md2DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")
 
 | 方法 | 说明 |
 |------|------|
-| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体） |
-| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件 |
-| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用） |
+| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体、图片内嵌） |
+| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件（图片输出 `<figure><img>`） |
+| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用；图片等比限宽居中） |
 
 > `dest_path=None` 时输出到源文件同目录；同一源文件不支持并发转换。
 
+**图片**：`![alt](相对路径)` 以 Markdown 源文件所在目录为基准解析，宽度等比限幅
+（96dpi 还原自然尺寸、不放大），超高先分页/按版心收紧；缺图、越界路径、非图片
+格式一律回落 `alt` 文本，不抛异常。远程地址在 PDF / Word 中不下载（回落 alt），
+在 HTML 中直出 `<img src="https://…">` 交给浏览器。HTML 输出保留相对路径，需与
+`images/` 目录保持同层级才能在浏览器中显示。
+
 ---
 
 ## kit.docs.mineru_kit —— MinerU 文档解析

{sdpy_kit-0.6.3 → sdpy_kit-0.6.4}/README.md

@@ -22,7 +22,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
 | `kit.docs.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
-| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML | `md2doc` |
+| `kit.docs.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML（含图片） | `md2doc` |
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
 | `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
@@ -49,7 +49,7 @@ uv add sdpy-kit
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
 | `ai` | AI 服务池（httpx + python-dotenv） | `pip install "sdpy-kit[ai]"` |
-| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2） | `pip install "sdpy-kit[md2doc]"` |
+| `md2doc` | Md2DocKit：Markdown → Word / PDF / HTML（pimd / fpdf2，含图片） | `pip install "sdpy-kit[md2doc]"` |
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `docx-parse` | RcDocParserKit 离线 docx 解析（rc-docparser → Markdown + images/） | `pip install "sdpy-kit[docx-parse]"` |
@@ -1000,12 +1000,18 @@ Md2DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")
 
 | 方法 | 说明 |
 |------|------|
-| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体） |
-| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件 |
-| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用） |
+| `convert_md_to_docx(src_path, dest_path=None, *, generate_toc=False, mainfont="宋体", reference_doc=None) -> str` | Markdown → Word（可插目录、统一字体、图片内嵌） |
+| `convert_md_to_html(src_path, dest_path=None, *, title=None) -> str` | Markdown → 独立 HTML5 文件（图片输出 `<figure><img>`） |
+| `convert_md_to_pdf(src_path, dest_path=None, *, mainfont="SimSun") -> str` | Markdown → PDF（实验性，内部使用；图片等比限宽居中） |
 
 > `dest_path=None` 时输出到源文件同目录；同一源文件不支持并发转换。
 
+**图片**：`![alt](相对路径)` 以 Markdown 源文件所在目录为基准解析，宽度等比限幅
+（96dpi 还原自然尺寸、不放大），超高先分页/按版心收紧；缺图、越界路径、非图片
+格式一律回落 `alt` 文本，不抛异常。远程地址在 PDF / Word 中不下载（回落 alt），
+在 HTML 中直出 `<img src="https://…">` 交给浏览器。HTML 输出保留相对路径，需与
+`images/` 目录保持同层级才能在浏览器中显示。
+
 ---
 
 ## kit.docs.mineru_kit —— MinerU 文档解析

{sdpy_kit-0.6.3 → sdpy_kit-0.6.4}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.6.3"
+__version__ = "0.6.4"
 
 from kit.db import (
     MYSQL,

{sdpy_kit-0.6.3 → sdpy_kit-0.6.4}/kit/docs/md2doc_kit.py

@@ -26,6 +26,9 @@ Author: Clark Chang
 - 全部静态方法、无内部状态；PiMD 转换引擎为模块级单例（自带 MemoryCache）。
 - Word 走 PiMD 引擎 + 表格撑满/全局字体后处理；PDF 与 HTML 同源解析
   （markdown-it），PDF 由内置 fpdf2 渲染器生成，观感向 HTML 对齐。
+- 图片：PDF 由 fpdf2 直接绘制；Word 用占位标记 + python-docx 回填真实图片；
+  HTML 用占位标记 + 后处理输出 `<figure><img>`。三者均以 Markdown 源文件
+  所在目录为相对路径基准，缺图/越界/不支持格式回落 alt 文本（不抛异常）。
 - 转换前统一改写 CJK 加粗定界符：CommonMark 定界规则下 `**加粗：**后接`
   会把星号作为字面量漏进产物。
 
@@ -33,16 +36,24 @@ Author: Clark Chang
 - 输入必须是 `.md` 文件路径；转换期间使用固定名临时文件
   （`.{源文件名}.pimd-tmp.md`），**同一源文件的并发调用不受支持**。
 - 代码块无背景填充等与 HTML 的已知差异，见对应方法说明。
+- 图片仅支持本地相对路径（`images/a.png` 形式）；远程 URL 在 PDF/Word
+  中回落为 alt 文本（不取网），在 HTML 中直接输出 `<img src>` 交由浏览器。
 
 依赖：
 - `pimd` + `markdown-it-py` + `fpdf2`（extra `md2doc`）；
   未安装时导入报错并提示安装命令。
+- 图片能力另需 Pillow（`fpdf2` 硬依赖）与 python-docx（`pimd` 硬依赖），
+  均由上游保证，不单独声明；缺失时按 ImportError 降级（回落 0.6.3 行为）。
 """
 
+import importlib.util
 import os
 import re
 import zipfile
+from html import escape as _html_escape
 from pathlib import Path
+from typing import Any
+from urllib.parse import unquote, urlsplit
 
 try:
     from fpdf import FPDF
@@ -214,6 +225,10 @@ img {
   max-width: 100%;
   height: auto;
 }
+figure.md2doc-img {
+  margin: 1em 0;
+  text-align: center;
+}
 @media (max-width: 720px) {
   body {
     padding: 0.5em 0.8em 2em;
@@ -363,6 +378,163 @@ def _polish_docx_font(docx_path: Path, font_name: str) -> None:
     tmp.replace(docx_path)
 
 
+# 图片占位标记（_extract_images 可能改用备用前缀）：@@MD2DOC[X]-IMG-{n}@@
+_DOCX_IMG_MARK_RE = re.compile(r"@@MD2DOCX?-IMG-(\d+)@@")
+# EMU ↔ mm：1mm = 36000 EMU（914400 EMU/inch ÷ 25.4）
+_EMU_PER_MM = 36000.0
+
+
+def _replace_marker_text(para: Any, marker: str, replacement: str) -> bool:
+    """把段落中的占位标记文本替换为 replacement（按 `w:t` 节点逐个替换）
+
+    直接遍历段落 XML 内的 `<w:t>` 文本节点，而非 `para.runs`：后者不包含
+    `<w:hyperlink>` 内的 run，`[![图](路径)](链接)` 这类链接包裹图片的标记
+    会残留在超链接里（python-docx 的既有行为）。
+
+    标记被拆进多个文本节点（PiMD 极少出现）时退化为整段纯文本重建，字符级
+    样式会丢失并记 warning。
+
+    Args:
+        para: python-docx 段落对象
+        marker: 占位标记文本
+        replacement: 替换文本（空串表示删除标记）
+
+    Returns:
+        bool: 是否找到该标记并替换成功
+    """
+    for node in para._p.iter():
+        if not node.tag.endswith("}t"):
+            continue
+        if node.text and marker in node.text:
+            node.text = node.text.replace(marker, replacement)
+            return True
+    if marker not in (para.text or ""):
+        return False
+    remaining = para.text.replace(marker, replacement)
+    for node in para._p.iter():
+        if node.tag.endswith("}t"):
+            node.text = ""
+    if remaining:
+        para.add_run(remaining)
+    logger.warning("图片占位标记跨节点拆分，已按纯文本重建段落")
+    return True
+
+
+def _drop_paragraph(para: Any) -> None:
+    """从文档树中移除段落（图片标记段清理后为空时使用）"""
+    element = para._p
+    element.getparent().remove(element)
+
+
+def _docx_available() -> bool:
+    """python-docx 是否可导入（pimd 硬依赖；缺失时 Word 图片回填整体降级）
+
+    Returns:
+        bool: 可用返回 True；不可用时 Word 输出保持 0.6.3 的 alt 超链接行为
+    """
+    try:
+        return importlib.util.find_spec("docx") is not None
+    except (ImportError, ValueError):
+        return False
+
+
+def _inject_docx_images(
+    docx_path: Path, refs: list[tuple[str, str]], base_dir: Path
+) -> None:
+    """把正文中的图片占位标记替换为真实图片段落（python-docx 后处理）
+
+    PiMD（markdown-it）会把行内图片降级为「alt 文本 + 指向 src 的超链接」，
+    docx 内没有 `word/media/`。本函数按占位标记回填：
+
+    - 标记所在段落中的标记文本删除，全部处理完且段落为空则整段移除；
+    - 标记段之后依次插入居中的图片段落（同段多图保持源顺序），宽高按节
+      内容区等比限幅（96dpi 基准）；
+    - 图片不可用（缺失 / 越界 / python-docx 不支持的格式如 webp）→ 标记替换
+      为 alt 文本并 warning，不抛异常（保持导出可用）。
+
+    必须在 `_polish_table_layout` / `_polish_docx_font` 之前调用：两次后处理
+    直接改写 docx 包内 XML，先插图片再 polish 才能保证二者互不覆盖。
+
+    Args:
+        docx_path: 待回填的 docx 路径（原地修改）
+        refs: `_extract_images` 返回的 (src, alt) 序列
+        base_dir: 相对路径基准目录（Markdown 源文件所在目录）
+    """
+    try:
+        from docx import Document
+        from docx.enum.text import WD_ALIGN_PARAGRAPH
+        from docx.image.image import Image as DocxImage
+        from docx.shared import Mm
+    except ImportError as e:  # python-docx 由 pimd 硬依赖提供，理论不可达
+        logger.warning(f"python-docx 不可用，跳过 Word 图片回填: {e}")
+        return
+
+    doc = Document(str(docx_path))
+    if not doc.sections:
+        return
+    section = doc.sections[0]
+    # Length 是 int 子类，减法会丢 .mm 属性，故按 EMU 换算
+    content_w = (
+        int(section.page_width) - int(section.left_margin) - int(section.right_margin)
+    ) / _EMU_PER_MM
+    content_h = (
+        int(section.page_height) - int(section.top_margin) - int(section.bottom_margin)
+    ) / _EMU_PER_MM
+
+    changed = False
+    for para in list(doc.paragraphs):
+        if not _DOCX_IMG_MARK_RE.search(para.text or ""):
+            continue
+        changed = True
+        # 同段多张图（`![a](x) ![b](y)`）逐个处理：锚点跟随新插入的段落，
+        # 保证图片顺序与源文档一致（若固定插在标记段之后顺序会反转）
+        anchor = para._p
+        while True:
+            match = _DOCX_IMG_MARK_RE.search(para.text or "")
+            if match is None:
+                break
+            marker = match.group(0)
+            idx = int(match.group(1))
+            src, alt = refs[idx] if idx < len(refs) else ("", "")
+
+            path = _resolve_local_image(src, base_dir)
+            fitted: tuple[float, float] | None = None
+            if path is not None:
+                try:
+                    info = DocxImage.from_file(str(path))
+                    fitted = _fit_size(
+                        info.px_width, info.px_height, content_w, content_h
+                    )
+                except Exception as e:  # noqa: BLE001 - 格式不支持统一回落
+                    logger.warning(f"Word 图片不可用，保留 alt 文本: {src}: {e}")
+                    fitted = None
+            if fitted is None:
+                # 不可用：标记换成 alt 文本；替换失败须跳出，避免死循环
+                if not _replace_marker_text(para, marker, alt):
+                    logger.warning(f"Word 图片标记无法清除，跳过: {marker}")
+                    break
+                continue
+
+            width, _height = fitted
+            if not _replace_marker_text(para, marker, ""):
+                logger.warning(f"Word 图片标记无法清除，跳过: {marker}")
+                break
+            new_para = doc.add_paragraph()
+            # 先挪到锚点之后，再（必要时）删除空标记段，顺序反了会失去锚点
+            anchor.addnext(new_para._p)
+            anchor = new_para._p
+            new_para.alignment = WD_ALIGN_PARAGRAPH.CENTER
+            new_para.paragraph_format.space_before = 0
+            new_para.paragraph_format.space_after = 0
+            new_para.add_run().add_picture(str(path), width=Mm(width))
+        # 全部标记处理完再判断：段落已空则删除（图片段落已插好，锚点安全）
+        if not (para.text or "").strip():
+            _drop_paragraph(para)
+
+    if changed:
+        doc.save(str(docx_path))
+
+
 # 中文字体表（单一数据源）：族名 / Windows 字体文件名 / 别名（小写）
 _CN_FONT_TABLE: tuple[tuple[str, str, tuple[str, ...]], ...] = (
     ("SimSun", "simsun.ttc", ("simsun", "宋体")),
@@ -428,6 +600,227 @@ def _fpdf_font_key(mainfont: str) -> tuple[str | None, str | None]:
     return (None, None)
 
 
+# ---- 图片能力公共助手（PDF / Word / HTML 三格式共用）----
+
+# 支持的图片后缀（Pillow 可读；SVG 不在此列，避免内嵌位图与外链面）
+_IMAGE_SUFFIXES = frozenset({".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp"})
+# 图片自然尺寸统一按 96dpi 换算：fpdf2 仅在给定 w 时按 horz_dpi 反推高度，
+# 与像素比、vert_dpi 均可能不一致；三格式统一基准并显式给出宽高可消除歧义。
+_IMAGE_DPI = 96.0
+_IMAGE_MM_PER_PX = 25.4 / _IMAGE_DPI
+# Markdown 图片语法：alt 内不含 ]，src 内不含括号与空白，可选 "title"
+_MD_IMAGE_RE = re.compile(
+    r'!\[(?P<alt>[^\]\n]*)\]\((?P<src>[^()\s]*)(?:\s+"(?P<title>[^"\n]*)")?\)'
+)
+# Word/HTML 回填用的占位标记前缀（与原文撞车时改用备用前缀）
+_MD_IMG_MARK = "@@MD2DOC-IMG-"
+_MD_IMG_MARK_ALT = "@@MD2DOCX-IMG-"
+
+
+def _resolve_local_image(src: str | None, base_dir: Path | None) -> Path | None:
+    """把 Markdown 图片 src 解析为 base_dir 子树内的本地文件路径
+
+    仅接受本地相对路径：拒绝带 scheme 的地址（`http(s)://`、`data:`、
+    `file://`）、协议相对（`//host/x.png`）以及越出 base_dir 的路径
+    （`../`），后缀须在 `_IMAGE_SUFFIXES` 白名单内。任何不可用情况返回
+    None（调用方回落 alt 文本），不抛异常。
+
+    Args:
+        src: Markdown 图片语法中的目标地址
+        base_dir: 相对路径基准目录（通常为 Markdown 源文件所在目录）
+
+    Returns:
+        Path | None: 可读取的本地图片绝对路径；不可用返回 None
+    """
+    if not src or base_dir is None:
+        return None
+    raw = unquote(src.strip().strip("<>"))
+    # 剥离 query / fragment 后再判本地性（`images/a.png?t=1` 仍算本地）
+    raw = raw.split("#", 1)[0].split("?", 1)[0]
+    if not raw:
+        return None
+    parts = urlsplit(raw)
+    if parts.scheme or parts.netloc or raw.startswith("//"):
+        return None
+    try:
+        root = Path(base_dir).resolve()
+        path = (root / raw).resolve()
+    except OSError:
+        return None
+    if path.suffix.lower() not in _IMAGE_SUFFIXES:
+        return None
+    if not path.is_relative_to(root) or not path.is_file():
+        return None
+    return path
+
+
+def _fit_size(
+    px_w: int, px_h: int, max_w: float, max_h: float
+) -> tuple[float, float] | None:
+    """按 96dpi 把像素尺寸换算为 mm，并用单一缩放因子同时满足宽高上限
+
+    宽高同因子保证等比；不放大（scale ≤ 1）。宽高任一非正或上限非正时
+    返回 None（调用方回落 alt 文本）。
+
+    Args:
+        px_w: 图片像素宽
+        px_h: 图片像素高
+        max_w: 可用宽度上限（mm）
+        max_h: 可用高度上限（mm）
+
+    Returns:
+        tuple[float, float] | None: (宽 mm, 高 mm)；参数非法返回 None
+    """
+    if px_w <= 0 or px_h <= 0 or max_w <= 0 or max_h <= 0:
+        return None
+    nat_w = px_w * _IMAGE_MM_PER_PX
+    nat_h = px_h * _IMAGE_MM_PER_PX
+    scale = min(1.0, max_w / nat_w, max_h / nat_h)
+    return nat_w * scale, nat_h * scale
+
+
+def _extract_images(markdown: str) -> tuple[str, list[tuple[str, str]]]:
+    """把 Markdown 图片语法替换为占位标记，供 Word / HTML 后处理回填
+
+    返回 (改写后的 Markdown, [(src, alt), ...])，第 i 个标记为
+    `@@MD2DOC-IMG-{i}@@`（与原文撞车时改用 `@@MD2DOCX-IMG-{i}@@`）。
+
+    与 `_normalize_cjk_bold` 同款状态机：围栏代码块、行内代码、GFM 表格块内
+    一律不改写——代码示例中的 `![x](y)` 必须原样保留；表格单元格在 0.6.3
+    中本就不解析行内 Markdown（图片语法以字面文本出现），本期维持该行为。
+    alt 内含 `]` 等不符合常规写法的图片语法不匹配，保持原样（即 0.6.3 的
+    alt 超链接降级行为），不做兜底改写。
+
+    Args:
+        markdown: 已完成 CJK 加粗预处理的 Markdown 文本
+
+    Returns:
+        tuple[str, list[tuple[str, str]]]: (改写后文本, [(src, alt), ...])
+    """
+    if "![" not in markdown:
+        return markdown, []
+
+    prefix = _MD_IMG_MARK
+    if prefix in markdown:
+        prefix = _MD_IMG_MARK_ALT
+        if prefix in markdown:
+            logger.warning(
+                "Markdown 已含图片占位标记前缀，跳过图片回填: "
+                f"{_MD_IMG_MARK!r} / {_MD_IMG_MARK_ALT!r}"
+            )
+            return markdown, []
+
+    refs: list[tuple[str, str]] = []
+    out_lines: list[str] = []
+    lines = markdown.splitlines(keepends=True)
+    in_fence = False
+    fence_marker = ""
+    in_table = False
+    for idx, line in enumerate(lines):
+        stripped = line.lstrip()
+        if not in_fence and (stripped.startswith("```") or stripped.startswith("~~~")):
+            in_fence = True
+            fence_marker = stripped[:3]
+            in_table = False
+            out_lines.append(line)
+            continue
+        if in_fence:
+            if stripped.startswith(fence_marker):
+                in_fence = False
+            out_lines.append(line)
+            continue
+        if in_table:
+            is_table = _is_table_row(line)
+        else:
+            is_table = (
+                _is_table_row(line)
+                and idx + 1 < len(lines)
+                and _is_table_delim(lines[idx + 1])
+            )
+        in_table = is_table
+        if is_table:
+            out_lines.append(line)
+            continue
+        # 行内代码段（1~3 个反引号包裹）保护：不做改写
+        segments = re.split(r"(`+[^`]*`+)", line)
+        pieces: list[str] = []
+        for seg in segments:
+            if seg.startswith("`"):
+                pieces.append(seg)
+                continue
+
+            def _sub(match: re.Match[str]) -> str:
+                refs.append((match.group("src"), match.group("alt")))
+                return f"{prefix}{len(refs) - 1}@@"
+
+            pieces.append(_MD_IMAGE_RE.sub(_sub, seg))
+        out_lines.append("".join(pieces))
+    return "".join(out_lines), refs
+
+
+def _html_img_tag(src: str, alt: str) -> str:
+    """构造 `<img>` 标签：路径反斜杠归一为 `/`，src/alt 均做 HTML 转义"""
+    safe_src = _html_escape(src.replace("\\", "/"))
+    safe_alt = _html_escape(alt)
+    return f'<img src="{safe_src}" alt="{safe_alt}">'
+
+
+def _inject_html_images(
+    html: str, refs: list[tuple[str, str]], base_dir: Path
+) -> str:
+    """把 HTML 中的图片占位标记替换为 `<figure><img>`（HTML 后处理）
+
+    PiMD（markdown-it）会把行内图片降级为 `<a href="src">alt</a>`，本函数按
+    占位标记重建图片：
+
+    - 独立成段的标记 → `<figure class="md2doc-img"><img …></figure>`，整体
+      替换 `<p>标记</p>`，避免出现 `<p><figure>` 非法嵌套；
+    - 段内混排（含 `[![x](y)](url)` 的链接内图片）→ 原位替换为 `<img>`；
+    - 本地图片不可用（缺失/越界/非白名单）→ 回落纯 alt 文本，不输出破图；
+    - 远程地址 → 输出 `<img src="https://…">` 交浏览器加载（服务端不取网）。
+
+    Args:
+        html: PiMD 转换后的完整 HTML 文本
+        refs: `_extract_images` 返回的 (src, alt) 序列
+        base_dir: 相对路径基准目录（Markdown 源文件所在目录）
+
+    Returns:
+        str: 替换后的 HTML 文本
+    """
+    for idx, (src, alt) in enumerate(refs):
+        marker = f"{_MD_IMG_MARK}{idx}@@"
+        if marker not in html:
+            marker = f"{_MD_IMG_MARK_ALT}{idx}@@"
+            if marker not in html:
+                continue
+        path = _resolve_local_image(src, base_dir)
+        parts = urlsplit(unquote(src.strip().strip("<>")))
+        is_remote = bool(parts.scheme or parts.netloc) or src.strip().startswith(
+            "//"
+        )
+        if path is not None:
+            rel = path.relative_to(Path(base_dir).resolve()).as_posix()
+            figure = (
+                f'<figure class="md2doc-img">{_html_img_tag(rel, alt)}</figure>'
+            )
+            inline = _html_img_tag(rel, alt)
+        elif is_remote:
+            figure = (
+                f'<figure class="md2doc-img">'
+                f"{_html_img_tag(src.strip(), alt)}</figure>"
+            )
+            inline = _html_img_tag(src.strip(), alt)
+        else:
+            figure = f"<p>{_html_escape(alt)}</p>" if alt else ""
+            inline = _html_escape(alt)
+        # 独立成段先整体替换，剩余（段内/链接内）标记再原位替换
+        html = re.sub(
+            r"<p>\s*" + re.escape(marker) + r"\s*</p>", lambda _m: figure, html
+        )
+        html = html.replace(marker, inline)
+    return html
+
+
 class _PdfMarkdownRenderer:
     """markdown-it token 流 → fpdf2 渲染器（与 convert_md_to_html 同源解析）
 
@@ -440,7 +833,11 @@ class _PdfMarkdownRenderer:
     行推进模型：fpdf2 的 write 结束后光标停在最后一行顶部（当前行高度
     未消费），凡经 write 渲染的块收尾必须 ln(整行高 + 块间隙)，否则
     相邻文本行纵向重叠；multi_cell 系块（表格/代码块）收尾 y 已在块
-    底部，其后 ln 仅为纯块间距。
+    底部，其后 ln 仅为纯块间距。图片按块级独占一行绘制（等比限宽居中），
+    块尾自行 ln(高度 + 间隙)，其所在段落不再按文本行推进。
+
+    图片仅渲染本地相对路径（基准为本 Markdown 源文件目录）；缺图、越界、
+    非白名单格式、远程地址一律回落为 alt 文本，保证导出可用。
     """
 
     _BODY_SIZE = 11
@@ -458,10 +855,18 @@ class _PdfMarkdownRenderer:
     # 手动排版（表格/代码块）以同一阈值判断分页，避免越界
     _BOTTOM_LIMIT = 20
 
-    def __init__(self, pdf: FPDF, font_key: str | None, has_cjk_font: bool) -> None:
+    def __init__(
+        self,
+        pdf: FPDF,
+        font_key: str | None,
+        has_cjk_font: bool,
+        base_dir: Path | None = None,
+    ) -> None:
         self.pdf = pdf
         self.font_key = font_key
         self.has_cjk_font = has_cjk_font
+        # 图片相对路径基准目录；None 表示不渲染图片（等价 0.6.3 行为）
+        self.base_dir = base_dir
         self._bold = False
         self._italic = False
         self._href: str | None = None
@@ -555,16 +960,33 @@ class _PdfMarkdownRenderer:
         pdf.write(h, label, link=self._href or "")
         pdf.set_text_color(*self._text_color)
 
-    def _render_inline(self, children: list[Token], size: int) -> None:
+    def _render_inline(self, children: list[Token], size: int) -> bool:
+        """渲染行内 token 流；返回「末个有效 token 是否为块级图片」
+
+        返回值供段落收尾判断：图片块已自行推进整行高，段落若再按文本行推进
+        会多出约一个行高的空白；行内混排（文字 + 图片 + 文字）仍返回 False。
+
+        Args:
+            children: 行内 token 序列（paragraph/heading/list_item 内的 children）
+            size: 当前字号（pt）
+
+        Returns:
+            bool: 末个有效 token 是否为已绘制成功的块级图片
+        """
+        last_image = False
         for tok in children:
             t = tok.type
             if t == "text":
                 self._flow_run(tok.content, size)
+                if tok.content.strip():
+                    last_image = False
             elif t == "softbreak":
                 self._write_run(" ", size)
+                last_image = False
             elif t == "hardbreak":
                 self.pdf.ln(self._line_h(size))
                 self.pdf.set_x(self.pdf.l_margin)
+                last_image = False
             elif t == "strong_open":
                 self._bold = True
             elif t == "strong_close":
@@ -579,8 +1001,65 @@ class _PdfMarkdownRenderer:
                 self._href = None
             elif t == "code_inline":
                 self._render_code_span(tok.content, size)
+                last_image = False
             elif t == "image":
-                self._flow_run(tok.content or "", size)
+                last_image = self._render_image(tok, size)
+        return last_image
+
+    def _render_image(self, tok: Token, size: int) -> bool:
+        """块级图片：按正文可用宽限宽、等比居中绘制；不可用时回落 alt 文本
+
+        图片独占一行（与 `_render_code_span` 的手动排版模型一致）：当前行已有
+        内容先换行，剩余空间不足先分页，绘制后 `ln(高度 + 间隙)` 推进整行并
+        把光标复位到当前左边距（列表/引用块内自动跟随缩进）。
+
+        宽高同时显式传给 fpdf2（`w`/`h`），不使用「只给 w 由 fpdf2 反推高度」
+        的方式——后者按 `horz_dpi` 换算，与像素比/`vert_dpi` 均可能不一致。
+
+        Args:
+            tok: markdown-it 的 image token（`src` 属性 + alt 作为 content）
+            size: 当前字号（pt），用于换行与回落文本排版
+
+        Returns:
+            bool: 是否成功绘制图片（False 表示已回落为 alt 文本）
+        """
+        alt = tok.content or ""
+        path = _resolve_local_image(tok.attrGet("src"), self.base_dir)
+        if path is None:
+            self._flow_run(alt, size)
+            return False
+        try:
+            # 图片尺寸读取：Pillow 由 fpdf2 硬依赖提供，缺失时按不可用处理
+            from PIL import Image
+
+            with Image.open(path) as image:
+                px_w, px_h = image.size
+        except Exception as e:  # noqa: BLE001 - 缺 Pillow / 坏图统一回落
+            logger.warning(f"图片不可读，回落为 alt 文本: {path.name}: {e}")
+            self._flow_run(alt, size)
+            return False
+
+        pdf = self.pdf
+        avail_w = pdf.w - pdf.l_margin - pdf.r_margin
+        max_h = pdf.h - pdf.t_margin - self._BOTTOM_LIMIT - 2
+        fitted = _fit_size(px_w, px_h, avail_w, max_h)
+        if fitted is None:
+            self._flow_run(alt, size)
+            return False
+        width, height = fitted
+
+        if pdf.get_x() > pdf.l_margin:
+            pdf.ln(self._line_h(size))
+        self._ensure_space(height + 3)
+        x = pdf.l_margin + (avail_w - width) / 2
+        try:
+            pdf.image(str(path), x=x, y=pdf.get_y(), w=width, h=height)
+        except Exception as e:  # noqa: BLE001 - 解码/格式异常统一回落
+            logger.warning(f"图片渲染失败，回落为 alt 文本: {path.name}: {e}")
+            self._flow_run(alt, size)
+            return False
+        pdf.ln(height + 3)
+        return True
 
     # ---- 块级渲染 ----
 
@@ -599,10 +1078,14 @@ class _PdfMarkdownRenderer:
                 return i
             if t == "paragraph_open":
                 self._ensure_space(self._line_h(self._BODY_SIZE) * 2)
-                self._render_inline(tokens[i + 1].children or [], self._BODY_SIZE)
+                ended_with_image = self._render_inline(
+                    tokens[i + 1].children or [], self._BODY_SIZE
+                )
                 # fpdf2 的 write 结束后光标停在最后一行顶部（未消费行高），
-                # 须推进整行高结束该行，再加段间隙；只推进小间隙会与后文重叠
-                self.pdf.ln(self._line_h(self._BODY_SIZE) + 1.2)
+                # 须推进整行高结束该行，再加段间隙；只推进小间隙会与后文重叠。
+                # 图片块已自行 ln(高度 + 间隙)，此处只补段间隙，避免双倍留白。
+                gap = 1.2 if ended_with_image else self._line_h(self._BODY_SIZE) + 1.2
+                self.pdf.ln(gap)
                 i += 3
             elif t.startswith("heading_"):
                 level = int(tok.tag[1])
@@ -760,10 +1243,13 @@ class _PdfMarkdownRenderer:
                 if not first_para:
                     self._ensure_space(self._line_h(self._BODY_SIZE) * 2)
                     pdf.set_x(left)
-                self._render_inline(tokens[i + 1].children or [], self._BODY_SIZE)
+                ended_with_image = self._render_inline(
+                    tokens[i + 1].children or [], self._BODY_SIZE
+                )
                 # write 后光标停在最后一行顶部：推进整行高 + 项内段间隙，
-                # 保证下一列表项/段落不与本项末行重叠
-                pdf.ln(self._line_h(self._BODY_SIZE) + 0.8)
+                # 保证下一列表项/段落不与本项末行重叠；图片块已自行推进，
+                # 此处只补项内段间隙。
+                pdf.ln(0.8 if ended_with_image else self._line_h(self._BODY_SIZE) + 0.8)
                 first_para = False
                 i += 3
                 continue
@@ -946,13 +1432,18 @@ class _PdfMarkdownRenderer:
         pdf.set_y(y0 + row_h)
 
 
-def _pdf_render_markdown(md_text: str, dest: Path, mainfont: str) -> None:
+def _pdf_render_markdown(
+    md_text: str, dest: Path, mainfont: str, base_dir: Path | None = None
+) -> None:
     """markdown-it token 流驱动 fpdf2 渲染 Markdown 为 PDF（与 HTML 同源解析）
 
     - 解析：MarkdownIt(commonmark)+table，与 convert_md_to_html（PiMD 内部
       同为 markdown-it）结构理解一致；支持标题、嵌套列表（有序/无序）、
       引用块、围栏代码块、GFM 表格、分隔线，及行内粗体/斜体/行内代码/
-      链接/图片 alt 文本。
+      链接/图片。
+    - 图片：`base_dir` 为相对路径基准（调用方传 Markdown 源文件目录），
+      渲染为等比限宽居中的块级图片；缺图/越界/远程一律回落 alt 文本。
+      `base_dir=None` 时不解析图片，行为与 0.6.3 完全一致。
     - 中文不可走 PiMD 自带 PDF 通道：其 PDF 引擎为回退链（docx2pdf →
       libreoffice → pandoc → weasyprint → fpdf2），末端 fpdf2 实现为
       Helvetica 文本提取，均不支持 CJK；本渲染器按 mainfont 注册系统
@@ -977,7 +1468,10 @@ def _pdf_render_markdown(md_text: str, dest: Path, mainfont: str) -> None:
             pdf.add_font(font_key, style, font_path)
 
     tokens = _MD_PARSER.parse(md_text)
-    _PdfMarkdownRenderer(pdf, font_key, font_path is not None).render(tokens)
+    renderer = _PdfMarkdownRenderer(
+        pdf, font_key, font_path is not None, base_dir=base_dir
+    )
+    renderer.render(tokens)
     pdf.output(str(dest))
 
 
@@ -1093,6 +1587,11 @@ class Md2DocKit:
         排版默认值：A4 纵向、正文 11pt、h1~h6 分级加粗、表格撑满页宽、
         单元格换行、多页自适应分页。
 
+        图片（`![alt](相对路径)`）渲染为块级图片：相对路径以本 Markdown
+        源文件所在目录为基准，按 96dpi 还原自然尺寸后等比限宽居中，超高
+        先分页、不放大；缺图、越界路径、非图片格式、远程地址一律回落为
+        alt 文本，不抛异常。表格单元格内的图片仍按 alt 文本处理。
+
         转换前自动做 CJK 加粗预处理（详见 convert_md_to_docx）。
 
         Args:
@@ -1120,7 +1619,8 @@ class Md2DocKit:
         processed = _normalize_cjk_bold(src.read_text(encoding="utf-8"))
 
         try:
-            _pdf_render_markdown(processed, dest, mainfont)
+            # 图片相对路径基准 = 源文件目录（与 images/ 同级导出结构天然匹配）
+            _pdf_render_markdown(processed, dest, mainfont, src.parent)
         except Exception as e:  # noqa: BLE001 - fpdf2 渲染异常统一包装
             logger.error(f"PDF 渲染失败: {src.name}: {e}")
             raise RuntimeError(f"PDF 渲染失败: {src.name}: {e}") from e
@@ -1145,6 +1645,12 @@ class Md2DocKit:
         （body `max-width: 900px` 等）：正文容器放大至 60em 并居中，中文
         优先字体栈（宋体系/黑体系），表格撑满页宽、表头加粗，适配宽屏阅读。
 
+        图片（`![alt](相对路径)`）输出为 `<figure class="md2doc-img"><img>`：
+        本地路径以源文件所在目录为基准判定存在性，存在则输出**相对路径**
+        （故 HTML 需与 `images/` 处于同一目录层级才能在浏览器中正常显示）；
+        缺图/越界回落为 alt 文本（不输出破图）；远程地址直接输出
+        `<img src="https://…">` 交由浏览器加载（服务端不取网）。
+
         转换前自动做 CJK 加粗预处理（详见 convert_md_to_docx）。
 
         Args:
@@ -1171,6 +1677,8 @@ class Md2DocKit:
 
         # CJK 加粗预处理；临时 md 与源文件同目录，保证相对图片路径仍然可用
         processed = _normalize_cjk_bold(src.read_text(encoding="utf-8"))
+        # 图片语法先换占位标记（PiMD 会把它降级为 alt 超链接），转换后回填
+        processed, img_refs = _extract_images(processed)
         tmp_md = src.with_name(f".{src.stem}.pimd-tmp.md")
         tmp_md.write_text(processed, encoding="utf-8")
 
@@ -1201,6 +1709,9 @@ class Md2DocKit:
                     f"{html[head_close:]}"
                 )
         html = html.replace("</head>", f"{_MD_HTML_CSS}\n</head>", 1)
+        # 图片回填：把占位标记还原为 <figure><img>（缺图回落 alt 文本）
+        if img_refs:
+            html = _inject_html_images(html, img_refs, src.parent)
         dest.write_text(html, encoding="utf-8")
 
         logger.info(f"✅ HTML 生成成功: {dest}")
@@ -1225,6 +1736,11 @@ class Md2DocKit:
         reference_doc 参数仅保留签名兼容（PiMD 的 md_to_docx 不接收参考
         模板，传入不生效）。
 
+        图片（`![alt](相对路径)`）以内嵌图片段落回填：PiMD 会把行内图片
+        降级为「alt 文本 + 超链接」，此处按占位标记替换为真实图片并居中，
+        宽度按节内容区等比限幅（相对路径以源文件所在目录为基准）；图片
+        缺失、越界或 python-docx 不支持的格式（如 webp）回落为 alt 文本。
+
         转换前自动做 CJK 加粗预处理：`**加粗：**后接` 这类闭合 ** 前为
         全角标点的写法不满足 CommonMark 定界规则（会以字面星号进入
         Word），内部将其改写为 `**加粗**：后接`，代码块内容不受影响；
@@ -1261,6 +1777,13 @@ class Md2DocKit:
 
         # CJK 加粗预处理；临时 md 与源文件同目录，保证相对图片路径仍然可用
         processed = _normalize_cjk_bold(src.read_text(encoding="utf-8"))
+        # 图片语法先换占位标记（PiMD 会把它降级为 alt 超链接），转换后回填；
+        # python-docx 不可用时不做标记替换，保持 0.6.3 的 alt 超链接行为
+        img_refs: list[tuple[str, str]] = []
+        if _docx_available():
+            processed, img_refs = _extract_images(processed)
+        else:
+            logger.warning("python-docx 不可用，Word 输出保留 alt 文本超链接（无图片）")
         tmp_md = src.with_name(f".{src.stem}.pimd-tmp.md")
         tmp_md.write_text(processed, encoding="utf-8")
 
@@ -1275,6 +1798,9 @@ class Md2DocKit:
         finally:
             tmp_md.unlink(missing_ok=True)
 
+        # 图片回填：无图片时直接跳过（避免 python-docx 往返改变无图产物）
+        if img_refs:
+            _inject_docx_images(dest, img_refs, src.parent)
         # 表格版式后处理：撑满页宽并整体居中
         _polish_table_layout(dest)
         # 全局字体后处理：正文/标题统一为 mainfont（代码块保持等宽）