sdpy-kit 0.1.0__py3-none-any.whl

kit/doc_kit.py

@@ -0,0 +1,1502 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2026-08-30
+"""文档转换工具类，基于 anydoc + PiMD 实现文档与 Markdown 双向转换
+
+本模块封装 firecrawl-anydoc（pip 安装名 firecrawl-anydoc，import 名 anydoc），
+将 Word、PowerPoint、Excel、CSV、PDF 格式统一转为 GitHub-Flavored Markdown；
+并基于 PiMD（pimd >= 2.2.5）将 Markdown 反向转换为 Word（.docx）与独立
+HTML（PDF 由本模块内嵌的 fpdf2 渲染器直接生成，保证中文与表格完整）。
+
+设计要点：
+- 全部使用静态方法提供服务，无内部状态；PiMD 转换引擎为模块级单例，线程安全。
+- 低层 convert_to_md 直接抛出异常（与 FileKit 风格一致，便于精确定位）。
+- 高层 convert 返回 ConvertResult 结果对象，封装成功/失败状态，便于批量处理。
+- 路径参数统一支持 str 与 pathlib.Path，内部 resolve 为绝对路径。
+- md → Word/PDF/HTML 均为 GFM 语法，转换前统一改写 CJK 加粗定界符；
+  Word 走 PiMD 引擎 + 表格撑满/全局字体后处理，PDF 与 HTML 同源解析
+  （markdown-it），由本模块 fpdf2 渲染器生成，观感与 HTML 对齐。
+"""
+
+import os
+import re
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+import anydoc
+from fpdf import FPDF
+from markdown_it import MarkdownIt
+from markdown_it.token import Token
+from pimd import PiMD
+from pimd.exceptions import ConversionError
+
+from kit.config.log_config import get_default_logger
+
+logger = get_default_logger(__name__)
+
+# PiMD 转换引擎单例：内部自带 MemoryCache，按进程复用（线程安全）
+_PIMD = PiMD()
+
+# PDF 渲染解析器：与 convert_md_to_html（PiMD 内部）同为 markdown-it 解析，
+# 保证 PDF 与 HTML 对同一 Markdown 的结构理解一致（GFM 表格需显式启用）
+_MD_PARSER = MarkdownIt("commonmark").enable("table")
+
+# anydoc 支持的文件扩展名集合（用于本地快速校验与错误提示）
+_SUPPORTED_EXTENSIONS: frozenset[str] = frozenset(
+    {
+        # Word
+        ".doc",
+        ".docx",
+        # PowerPoint
+        ".ppt",
+        ".pptx",
+        # Excel
+        ".xls",
+        ".xlsx",
+        # 其他
+        ".csv",
+        ".pdf",
+    }
+)
+
+
+# CJK 加粗泄漏模式：闭合 ** 前为标点串、后紧跟文字（如 `**加粗：**后接`）。
+# PiMD（markdown-it，CommonMark 系）同样执行定界符规则，闭合 ** 须满足
+# right-flanking（不被标点前置，或被空白/标点后置），上述写法不满足，
+# 星号会以字面文本进入产物。改写策略：把尾部标点串移出粗体定界符。
+_CJK_BOLD_LEAK_RE = re.compile(
+    r"\*\*(?P<content>[^*\n]+?)(?P<punct>[^\w\s]+?)\*\*(?=\w)"
+)
+
+
+def _normalize_cjk_bold(markdown: str) -> str:
+    """规避 Markdown 引擎对中文加粗的 CommonMark 定界限制
+
+    两类处理：
+    - 普通文本行：将 `**加粗：**后接` 改写为 `**加粗**：后接`（尾部标点
+      移出粗体定界符），闭合 ** 后紧跟文字的泄漏场景；文本内容零增删。
+    - 表格行：PiMD 的表格单元格以纯文本写入（不解析行内 Markdown），
+      `**` 定界符必然字面泄漏，直接剥除定界符保留文本（表头自带加粗
+      样式，不依赖 `**`）。
+    围栏代码块与行内代码段不做处理。
+    """
+    out_lines: list[str] = []
+    in_fence = False
+    fence_marker = ""
+    for line in markdown.splitlines(keepends=True):
+        stripped = line.lstrip()
+        if not in_fence and (stripped.startswith("```") or stripped.startswith("~~~")):
+            in_fence = True
+            fence_marker = stripped[:3]
+            out_lines.append(line)
+            continue
+        if in_fence:
+            if stripped.startswith(fence_marker):
+                in_fence = False
+            out_lines.append(line)
+            continue
+        # 行内代码段（反引号包裹）保护：不做处理
+        segments = re.split(r"(`[^`]*`)", line)
+        is_table = _is_table_row(line)
+        fixed = "".join(
+            (
+                seg
+                if seg.startswith("`")
+                else (
+                    _strip_bold_delims(seg)
+                    if is_table
+                    else _CJK_BOLD_LEAK_RE.sub(r"**\g<content>**\g<punct>", seg)
+                )
+            )
+            for seg in segments
+        )
+        out_lines.append(fixed)
+    return "".join(out_lines)
+
+
+def _strip_bold_delims(text: str) -> str:
+    """剥除加粗/斜体定界符，保留文本内容（用于不解析行内格式的表格单元格）"""
+    text = re.sub(r"\*\*([^*]+)\*\*", r"\1", text)
+    text = re.sub(r"\*([^*]+)\*", r"\1", text)
+    return text
+
+
+# HTML 默认排版：覆盖 PiMD 自带 HTML 样式（body `max-width: 900px` 等默认值），
+# 注入方式为转换后插入 `</head>` 前（覆盖同名选择器声明）；CSS 侧重中文文档宽屏阅读。
+_MD_HTML_CSS = """<style>
+/* 默认不注入页面标题（PiMD 默认不输出 title 元素，显式传 title 时才会出现） */
+head title {
+  display: none;
+}
+body {
+  max-width: 60em;
+  margin: 0 auto;
+  padding: 1em 1.5em 3em;
+  font-size: 16px;
+  line-height: 1.7;
+  font-family: "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
+  color: #1a1a1a;
+  background-color: #fdfdfd;
+}
+h1, h2, h3, h4, h5, h6 {
+  line-height: 1.3;
+  margin-top: 1.4em;
+  margin-bottom: 0.5em;
+  font-weight: 600;
+  overflow-wrap: anywhere;
+}
+h1 { font-size: 2em; border-bottom: 1px solid #e6e6e6; padding-bottom: 0.3em; }
+h2 { font-size: 1.6em; border-bottom: 1px solid #e6e6e6; padding-bottom: 0.3em; }
+h3 { font-size: 1.3em; }
+h4, h5, h6 { font-size: 1.1em; }
+table {
+  width: 100%;
+  max-width: 100%;
+  border-collapse: collapse;
+  margin: 1em 0;
+  font-size: 0.95em;
+}
+th, td {
+  border: 1px solid #ccc;
+  padding: 6px 10px;
+  text-align: left;
+  vertical-align: top;
+}
+th {
+  background-color: #f0f0f0;
+  font-weight: 600;
+}
+pre {
+  background-color: #f6f8fa;
+  border: 1px solid #e6e6e6;
+  border-radius: 4px;
+  padding: 0.8em 1em;
+  overflow-x: auto;
+  line-height: 1.5;
+}
+code {
+  font-family: "Cascadia Code", Menlo, Consolas, monospace;
+  font-size: 0.9em;
+  background-color: #f6f8fa;
+  border-radius: 4px;
+  padding: 0.1em 0.35em;
+}
+pre code {
+  background-color: transparent;
+  padding: 0;
+}
+img {
+  max-width: 100%;
+  height: auto;
+}
+@media (max-width: 720px) {
+  body {
+    padding: 0.5em 0.8em 2em;
+    font-size: 15px;
+  }
+  table {
+    display: block;
+    overflow-x: auto;
+  }
+}
+</style>"""
+
+
+def _polish_table_layout(docx_path: Path) -> None:
+    """表格版式后处理：宽度撑满页宽并整体居中
+
+    转换引擎（PiMD 底层 python-docx）写出的 `tblW type=auto`
+    会使表格按内容收缩、不满页宽；将其替换为 pct 5000（100% 页宽）并
+    追加居中标记（jc 紧随 tblW，符合 OOXML 元素顺序），其余包内成员
+    原样重打包。无表格时为空操作。
+    """
+    marker = r'<w:tblW w:type="auto" w:w="0"\s*/>'
+    with zipfile.ZipFile(docx_path) as zin:
+        doc_xml = zin.read("word/document.xml").decode("utf-8")
+        if not re.search(marker, doc_xml):
+            return
+        polished = re.sub(
+            marker,
+            '<w:tblW w:type="pct" w:w="5000" />\n<w:jc w:val="center" />',
+            doc_xml,
+        )
+        tmp = docx_path.with_name(f".{docx_path.stem}.polish-tmp")
+        with zipfile.ZipFile(tmp, "w", zipfile.ZIP_DEFLATED) as zout:
+            for item in zin.infolist():
+                if item.filename == "word/document.xml":
+                    zout.writestr(item, polished)
+                else:
+                    zout.writestr(item, zin.read(item.filename))
+    tmp.replace(docx_path)
+
+
+# 等宽样式隔离：这些 styleId 的 rFonts 属于代码块，字体后处理跳过，
+# 保证代码块在全文宋体化后仍为等宽字体
+_MONO_STYLE_IDS = frozenset({"CodeBlock", "MacroText", "MacroTextChar"})
+# 显式字体名含此模式的样式视为等宽，同样跳过
+_MONO_FONT_RE = re.compile(
+    r"Courier|Consolas|Menlo|Monaco|Source Code|Lucida Console", re.I
+)
+
+
+def _polish_docx_font(docx_path: Path, font_name: str) -> None:
+    """全局字体后处理：docDefaults / 主题 / 样式级 rFonts 统一为指定字体
+
+    PiMD 产物正文西文走主题 minorFont（Calibri）、标题走 majorFont，
+    **且每个样式自带显式 rFonts**（样式级优先级高于 docDefaults 与主题）。
+    仅改写默认通道会在 Word 中仍显示 Calibri。因此此处三通道一起改写，
+    使全文统一为 font_name：
+    - styles.xml docDefaults：主题引用 rFonts 替换为显式四项字体（兜底）；
+    - theme1.xml：majorFont/minorFont 顶层 latin/ea/cs typeface 改写
+      （Heading 1~6 / Title 等走主题字体的样式兜底）；
+    - styles.xml 各 `<w:style>` 内 rFonts：显式 Calibri 替换为 font_name，
+      主题引用（majorHAnsi/majorEastAsia……）替换为显式四项 font_name。
+    等宽样式（CodeBlock/MacroText 等、Courier 系字体）跳过，保持代码块
+    等宽观感；run 级显式字体优先级最高，本处理不触及。
+    """
+    esc = font_name.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+    with zipfile.ZipFile(docx_path) as zin:
+        names = zin.namelist()
+        patched: dict[str, str] = {}
+        if "word/styles.xml" in names:
+            xml = zin.read("word/styles.xml").decode("utf-8")
+
+            def _rewrite_rfonts(m: re.Match[str]) -> str:
+                """单个 <w:rFonts .../> 重写：等宽样式跳过，其余统一字体
+
+                - 含主题引用（asciiTheme 等）→ 替换为显式四项字体；
+                - 显式字体（ascii/hAnsi/eastAsia/cs）→ 仅替换字体名，
+                  保留 style/val 等其他属性。
+                """
+                attrs = m.group(0)
+                style_head = xml.rfind("<w:style ", 0, m.start())
+                sid = None
+                if style_head != -1:
+                    sm = re.search(
+                        r'<w:style[^>]*w:styleId="([^"]+)"',
+                        xml[style_head : m.start()],
+                    )
+                    sid = sm.group(1) if sm else None
+                if sid in _MONO_STYLE_IDS or re.search(_MONO_FONT_RE, attrs):
+                    return attrs
+                if "w:asciiTheme" in attrs:
+                    return (
+                        f'<w:rFonts w:ascii="{esc}" w:eastAsia="{esc}" '
+                        f'w:hAnsi="{esc}" w:cs="{esc}" />'
+                    )
+                for prop in ("w:ascii", "w:hAnsi", "w:eastAsia", "w:cs"):
+                    attr_re = re.compile(rf"{re.escape(prop)}=\"[^\"]*\"")
+                    attrs = attr_re.sub(f'{prop}="{esc}"', attrs)
+                return attrs
+
+            new = re.sub(r"<w:rFonts[^>]*/>", _rewrite_rfonts, xml)
+            if new != xml:
+                patched["word/styles.xml"] = new
+        if "word/theme/theme1.xml" in names:
+            xml = zin.read("word/theme/theme1.xml").decode("utf-8")
+            scheme = re.search(r"<a:fontScheme.*?</a:fontScheme>", xml, re.S)
+            if scheme:
+                block = scheme.group(0)
+                new_block = re.sub(
+                    r'<a:latin typeface="[^"]*"', f'<a:latin typeface="{esc}"', block
+                )
+                new_block = re.sub(
+                    r'<a:ea typeface="[^"]*"', f'<a:ea typeface="{esc}"', new_block
+                )
+                new_block = re.sub(
+                    r'<a:cs typeface="[^"]*"', f'<a:cs typeface="{esc}"', new_block
+                )
+                if new_block != block:
+                    patched["word/theme/theme1.xml"] = xml.replace(block, new_block)
+        if not patched:
+            return
+        tmp = docx_path.with_name(f".{docx_path.stem}.font-tmp")
+        with zipfile.ZipFile(tmp, "w", zipfile.ZIP_DEFLATED) as zout:
+            for item in zin.infolist():
+                data = patched.get(item.filename)
+                if data is not None:
+                    zout.writestr(item, data)
+                else:
+                    zout.writestr(item, zin.read(item.filename))
+    tmp.replace(docx_path)
+
+
+def _font_search_paths() -> list[str]:
+    """收集系统可用的中文字体文件路径（存在才返回）
+
+    仅查询 Windows 字体目录（WINDIR/Fonts）下的常规中文字体（含 .ttc），
+    供 `_fpdf_font_key` 回退匹配使用。
+    """
+    windir = Path(os.environ.get("WINDIR", r"C:\Windows")) / "Fonts"
+    candidates: dict[tuple[str, ...], Path] = {
+        ("SimSun", "宋体", "SimSun-ExtB"): windir / "simsun.ttc",
+        ("SimHei", "黑体"): windir / "simhei.ttf",
+        ("Microsoft YaHei", "微软雅黑"): windir / "msyh.ttc",
+        ("KaiTi", "楷体"): windir / "simkai.ttf",
+        ("FangSong", "仿宋"): windir / "simfang.ttf",
+    }
+    paths: list[Path] = []
+    for _, fp in candidates.items():
+        if fp.is_file() and fp not in paths:
+            paths.append(fp)
+    for p in paths:
+        if p.is_file():
+            return [str(p)]
+    return []
+
+
+_FONT_ALIAS_MAP: dict[str, str] = {
+    "simsun": "SimSun",
+    "宋体": "SimSun",
+    "simhei": "SimHei",
+    "黑体": "SimHei",
+    "msyh": "MicrosoftYaHei",
+    "微软雅黑": "MicrosoftYaHei",
+    "kaiti": "KaiTi",
+    "楷体": "KaiTi",
+    "fangsong": "FangSong",
+    "仿宋": "FangSong",
+}
+
+# 族名 → Windows 字体文件名（ttc/ttf）；fpdf2 以 add_font 注册名引用
+_FONT_FILE_MAP: dict[str, tuple[str, ...]] = {
+    "SimSun": ("simsun.ttc",),
+    "SimHei": ("simhei.ttf",),
+    "MicrosoftYaHei": ("msyh.ttc",),
+    "KaiTi": ("simkai.ttf",),
+    "FangSong": ("simfang.ttf",),
+}
+
+
+def _fpdf_font_key(mainfont: str) -> tuple[str | None, str | None]:
+    """按 mainfont 名称匹配 fpdf2 可用的中文字体（fontfile + 注册名）
+
+    返回 (字体文件绝对路径, fpdf2 add_font 注册名)；名称先精确匹配别名表，
+    再模糊匹配（如 SimSun-ExtB），均未命中回退 SimSun（存在则优先）。
+    全部不可用时返回 (None, None)（PDF 将降级为 Helvetica，仅 ASCII 可读）。
+    """
+    lowered = mainfont.lower()
+    family = _FONT_ALIAS_MAP.get(lowered)
+    if family is None:
+        for alias, fam in _FONT_ALIAS_MAP.items():
+            if alias in lowered or lowered in alias:
+                family = fam
+                break
+    if family is None:
+        family = "SimSun"
+
+    windir = Path(os.environ.get("WINDIR", r"C:\Windows")) / "Fonts"
+    for fname in _FONT_FILE_MAP.get(family, ()):
+        fp = windir / fname
+        if fp.is_file():
+            return (str(fp), family)
+    # 回退到任意已知存在的中文字体
+    pool = _font_search_paths()
+    if pool:
+        return (pool[0], Path(pool[0]).stem)
+    return (None, None)
+
+
+class _PdfMarkdownRenderer:
+    """markdown-it token 流 → fpdf2 渲染器（与 convert_md_to_html 同源解析）
+
+    与 HTML 版观感对齐：标题分级加粗、正文 11pt、表格撑满页宽表头灰底、
+    引用块左侧竖线 + 灰字、行内代码灰底等宽、链接蓝色；嵌套列表逐层
+    缩进（fpdf2 的 write 自动换行回到 left_margin，天然实现悬挂缩进）。
+    行内样式经 pdf.write 流式切换字体渲染；表格单元格因需列内折行，
+    改用 multi_cell(markdown=False)（纯文本，表头灰底深色维持加粗观感，
+    规避 CJK 粗体字体未注册导致的崩溃）。
+    行推进模型：fpdf2 的 write 结束后光标停在最后一行顶部（当前行高度
+    未消费），凡经 write 渲染的块收尾必须 ln(整行高 + 块间隙)，否则
+    相邻文本行纵向重叠；multi_cell 系块（表格/代码块）收尾 y 已在块
+    底部，其后 ln 仅为纯块间距。
+    """
+
+    _BODY_SIZE = 11
+    _TABLE_SIZE = 10
+    _HEADING_SIZES = {1: 18, 2: 15, 3: 13, 4: 12, 5: 12, 6: 11}
+    _BULLET_MARKS = ("•", "○")  # GB2312 字库安全的项目符号
+    _QUOTE_TEXT_COLOR = (95, 95, 95)
+    _QUOTE_LINE_COLOR = (180, 180, 180)
+    _LINK_COLOR = (5, 99, 195)
+    _CODE_TEXT_COLOR = (51, 51, 51)
+    _CODE_BG_COLOR = (243, 244, 246)
+    _BORDER_COLOR = (204, 204, 204)
+    _HEAD_BG_COLOR = (240, 240, 240)
+    # 分页底限：与 set_auto_page_break(margin=20) 的 trigger 一致；
+    # 手动排版（表格/代码块）以同一阈值判断分页，避免越界
+    _BOTTOM_LIMIT = 20
+
+    def __init__(self, pdf: FPDF, font_key: str | None, has_cjk_font: bool) -> None:
+        self.pdf = pdf
+        self.font_key = font_key
+        self.has_cjk_font = has_cjk_font
+        self._base_left = pdf.l_margin
+        self._bold = False
+        self._italic = False
+        self._href: str | None = None
+        self._text_color: tuple[int, int, int] = (0, 0, 0)
+
+    # ---- 基础工具 ----
+
+    @property
+    def _family(self) -> str:
+        return self.font_key if self.has_cjk_font and self.font_key else "Helvetica"
+
+    def _style(self) -> str:
+        return ("B" if self._bold else "") + ("I" if self._italic else "")
+
+    def _line_h(self, size: int) -> float:
+        return size * 0.5
+
+    def _ensure_space(self, need: float) -> None:
+        """手动绘制前分页检查：剩余空间不足则换页"""
+        if self.pdf.get_y() + need > self.pdf.h - self._BOTTOM_LIMIT:
+            self.pdf.add_page()
+
+    def _avail_width(self) -> float:
+        """当前行可用宽度（从当前 x 到右边距）"""
+        return self.pdf.w - self.pdf.x - self.pdf.r_margin
+
+    # ---- 行内渲染（pdf.write 流式，样式即切即用）----
+
+    def _flow_run(self, text: str, size: int) -> None:
+        """流式写入文本，先在当前行剩余宽度内测宽排布；
+        放不下则手动画行到左边缘（悬挂缩进），再交给 write 补齐文本。
+        write 对超长片段自带按词折行与翻页，二者结合避免内容越右边界。
+        """
+        if not text:
+            return
+        pdf = self.pdf
+        h = self._line_h(size)
+        while text:
+            pdf.set_font(self._family, self._style(), size)
+            # 整段宽度放得下直接整段写入（保持词间不折行）
+            if pdf.get_string_width(text) <= self._avail_width():
+                self._write_run(text, size)
+                return
+            # 找当前行能容纳的最长前缀（按字符累计宽度）
+            prefix = ""
+            width = 0.0
+            for ch in text:
+                width += pdf.get_string_width(ch)
+                if width > self._avail_width():
+                    break
+                prefix += ch
+            if not prefix:
+                # 单个字符都放不下（极端窄列），直接交给 write 处理
+                self._write_run(text, size)
+                return
+            page_before = pdf.page_no()
+            self._write_run(prefix, size)
+            text = text[len(prefix) :]
+            if pdf.page_no() != page_before:
+                # writer 已触发翻页，剩余文本在新页顶部继续排
+                continue
+            pdf.ln(h)
+            pdf.set_x(pdf.l_margin)
+
+    def _write_run(self, text: str, size: int) -> None:
+        if not text:
+            return
+        pdf = self.pdf
+        pdf.set_font(self._family, self._style(), size)
+        color = self._LINK_COLOR if self._href else self._text_color
+        pdf.set_text_color(*color)
+        pdf.write(self._line_h(size), text, link=self._href or "")
+
+    def _render_code_span(self, content: str, size: int) -> None:
+        """行内代码：等宽小号 + 灰底（先画底色矩形再覆写文本）"""
+        pdf = self.pdf
+        code_size = max(size - 2, 8)
+        label = f" {content} "
+        pdf.set_font(self._family, "", code_size)
+        w = pdf.get_string_width(label)
+        h = self._line_h(size)
+        # 行内剩余宽度不足时先软换行到左边缘（保持悬挂缩进）
+        if w > self._avail_width():
+            pdf.ln(h)
+            pdf.set_x(pdf.l_margin)
+        x, y = pdf.get_x(), pdf.get_y()
+        pdf.set_fill_color(*self._CODE_BG_COLOR)
+        pdf.rect(x, y + 0.4, w + 2, h - 0.6, "F")
+        pdf.set_text_color(*self._CODE_TEXT_COLOR)
+        pdf.set_xy(x, y)
+        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:
+        for tok in children:
+            t = tok.type
+            if t == "text":
+                self._flow_run(tok.content, size)
+            elif t == "softbreak":
+                self._write_run(" ", size)
+            elif t == "hardbreak":
+                self.pdf.ln(self._line_h(size))
+                self.pdf.set_x(self.pdf.l_margin)
+            elif t == "strong_open":
+                self._bold = True
+            elif t == "strong_close":
+                self._bold = False
+            elif t == "em_open":
+                self._italic = True
+            elif t == "em_close":
+                self._italic = False
+            elif t == "link_open":
+                self._href = tok.attrGet("href") or ""
+            elif t == "link_close":
+                self._href = None
+            elif t == "code_inline":
+                self._render_code_span(tok.content, size)
+            elif t == "image":
+                self._flow_run(tok.content or "", size)
+
+    # ---- 块级渲染 ----
+
+    def render(self, tokens: list[Token]) -> None:
+        self._render_blocks(tokens, 0)
+
+    def _render_blocks(
+        self, tokens: list[Token], i: int, stop: str | None = None
+    ) -> int:
+        """顺序渲染块级 token 流；遇 stop 类型（如 blockquote_close）即返回"""
+        n = len(tokens)
+        while i < n:
+            tok = tokens[i]
+            t = tok.type
+            if stop is not None and t == stop:
+                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)
+                # fpdf2 的 write 结束后光标停在最后一行顶部（未消费行高），
+                # 须推进整行高结束该行，再加段间隙；只推进小间隙会与后文重叠
+                self.pdf.ln(self._line_h(self._BODY_SIZE) + 1.2)
+                i += 3
+            elif t.startswith("heading_"):
+                level = int(tok.tag[1])
+                self._render_heading(level, tokens[i + 1].children or [])
+                i += 3
+            elif t in ("bullet_list_open", "ordered_list_open"):
+                i = self._render_list(tokens, i, 0)
+            elif t == "blockquote_open":
+                i = self._render_blockquote(tokens, i)
+            elif t == "fence":
+                self._render_fence(tok)
+                i += 1
+            elif t == "table_open":
+                i = self._render_table(tokens, i)
+            elif t == "hr":
+                self._render_hr()
+                i += 1
+            else:
+                i += 1
+        return i
+
+    def _render_heading(self, level: int, children: list[Token]) -> None:
+        size = self._HEADING_SIZES.get(level, self._BODY_SIZE)
+        self._ensure_space(size * 1.8)
+        self.pdf.ln(2)
+        saved_bold = self._bold
+        self._bold = True  # 对齐 HTML：h1~h6 均 font-weight 600
+        self._render_inline(children, size)
+        self._bold = saved_bold
+        self.pdf.ln(self._line_h(size) + 1.5)
+
+    def _render_hr(self) -> None:
+        self._ensure_space(6)
+        pdf = self.pdf
+        pdf.set_draw_color(230, 230, 230)
+        pdf.set_line_width(0.4)
+        y = pdf.get_y() + 1.5
+        pdf.line(pdf.l_margin, y, pdf.w - pdf.r_margin, y)
+        pdf.ln(4)
+
+    def _render_fence(self, tok: Token) -> None:
+        """代码块：浅灰背景 + 等宽 9pt，长行先折再逐行输出
+
+        对齐 HTML 的 pre 样式：浅灰底、等宽字。每行先按可用宽度折行成
+        片段段，再逐段 multi_cell；页底不足时 add_page 续排（同一逻辑行
+        的续段在新页顶部继续，代码不错位）。行首固定缩进 2mm。
+        """
+        pdf = self.pdf
+        code_size = 9
+        line_h = 5
+        self._ensure_space(line_h * 2)
+        pdf.ln(1)
+        code_bottom = pdf.h - 20
+        for cl in tok.content.rstrip("\n").splitlines():
+            if not cl:
+                pdf.ln(line_h)
+                continue
+            # 长行按可用宽度折成多段（一次测宽，避免 multi_cell 内部换行打乱对齐）
+            chunks: list[str] = []
+            rest = cl
+            while rest and pdf.get_string_width(rest) > self._avail_width():
+                width = 0
+                split_at = len(rest)
+                for idx, ch in enumerate(rest):
+                    width += pdf.get_string_width(ch)
+                    if width > self._avail_width():
+                        split_at = idx
+                        break
+                chunks.append(rest[:split_at])
+                rest = rest[split_at:]
+            if rest:
+                chunks.append(rest)
+            for c in chunks:
+                if pdf.get_y() + line_h > code_bottom:
+                    pdf.add_page()
+                pdf.set_x(pdf.l_margin + 2)
+                pdf.set_font(self._family, "", code_size)
+                pdf.multi_cell(0, line_h, c)
+        pdf.ln(3)
+
+    def _render_blockquote(self, tokens: list[Token], i: int) -> int:
+        pdf = self.pdf
+        prev_left = pdf.l_margin
+        left = prev_left + 8
+        start_page = pdf.page_no()
+        self._ensure_space(self._line_h(self._BODY_SIZE) * 2)
+        y0 = pdf.get_y()
+        pdf.set_left_margin(left)
+        pdf.set_x(left)
+        saved_color = self._text_color
+        self._text_color = self._QUOTE_TEXT_COLOR
+        i = self._render_blocks(tokens, i + 1, stop="blockquote_close")
+        pdf.set_left_margin(prev_left)
+        self._text_color = saved_color
+        y1 = pdf.get_y()
+        # 左侧竖线（跨页引用仅绘制续页段，避免在旧页坐标误画）
+        pdf.set_draw_color(*self._QUOTE_LINE_COLOR)
+        pdf.set_line_width(0.6)
+        if pdf.page_no() == start_page:
+            pdf.line(left - 2.5, y0 + 0.5, left - 2.5, max(y1 - 1, y0 + 1.5))
+        else:
+            pdf.line(
+                left - 2.5, pdf.t_margin, left - 2.5, max(y1 - 1, pdf.t_margin + 1.5)
+            )
+        pdf.ln(2)
+        return min(i + 1, len(tokens))
+
+    def _render_list(self, tokens: list[Token], i: int, depth: int) -> int:
+        open_tok = tokens[i]
+        ordered = open_tok.type == "ordered_list_open"
+        try:
+            idx = int(open_tok.attrGet("start") or 1)
+        except (TypeError, ValueError):
+            idx = 1
+        n = len(tokens)
+        i += 1
+        while i < n:
+            tok = tokens[i]
+            t = tok.type
+            if t in ("bullet_list_close", "ordered_list_close"):
+                return i + 1
+            if t == "list_item_open":
+                if ordered:
+                    marker = f"{idx}."
+                    idx += 1
+                else:
+                    marker = self._BULLET_MARKS[depth % len(self._BULLET_MARKS)]
+                i = self._render_list_item(tokens, i + 1, depth, marker)
+                continue
+            i += 1
+        return i
+
+    def _render_list_item(
+        self, tokens: list[Token], i: int, depth: int, marker: str
+    ) -> int:
+        pdf = self.pdf
+        n = len(tokens)
+        prev_left = pdf.l_margin
+        left = prev_left + 6 * (depth + 1)
+        pdf.set_left_margin(left)
+        # 项目符号悬挂在缩进左侧
+        pdf.set_x(left - 6)
+        pdf.set_font(self._family, "", self._BODY_SIZE)
+        pdf.set_text_color(*self._text_color)
+        pdf.cell(
+            pdf.get_string_width(marker) + 1.5, self._line_h(self._BODY_SIZE), marker
+        )
+        first_para = True
+        while i < n and tokens[i].type != "list_item_close":
+            tok = tokens[i]
+            t = tok.type
+            if t == "paragraph_open":
+                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)
+                # write 后光标停在最后一行顶部：推进整行高 + 项内段间隙，
+                # 保证下一列表项/段落不与本项末行重叠
+                pdf.ln(self._line_h(self._BODY_SIZE) + 0.8)
+                first_para = False
+                i += 3
+                continue
+            if t in ("bullet_list_open", "ordered_list_open"):
+                pdf.ln(self._line_h(self._BODY_SIZE) * 0.3)
+                i = self._render_list(tokens, i, depth + 1)
+                continue
+            if t == "fence":
+                pdf.ln(1)
+                self._render_fence(tok)
+                i += 1
+                continue
+            if t == "blockquote_open":
+                i = self._render_blockquote(tokens, i)
+                continue
+            i += 1
+        pdf.set_left_margin(prev_left)
+        # 行推进已由项内段落/嵌套块按"整行高+间隙"收尾，此处不再额外
+        # 推进（原 ln(2) 在 write 行模型下是列表项纵向重叠的根因）
+        return min(i + 1, n)
+
+    def _render_table(self, tokens: list[Token], i: int) -> int:
+        """收集 thead/tbody 行列后交由 _draw_table 绘制"""
+        header: list[list[Token]] = []
+        body: list[list[list[Token]]] = []
+        n = len(tokens)
+        i += 1  # 跳过 table_open
+        while i < n and tokens[i].type != "table_close":
+            if tokens[i].type != "tr_open":
+                i += 1
+                continue
+            cells: list[list[Token]] = []
+            has_th = False
+            i += 1
+            while i < n and tokens[i].type != "tr_close":
+                if tokens[i].type in ("th_open", "td_open"):
+                    has_th = has_th or tokens[i].type == "th_open"
+                    cells.append(tokens[i + 1].children or [])
+                    i += 3
+                    continue
+                i += 1
+            i += 1  # tr_close
+            if not cells:
+                continue
+            if has_th and not header:
+                header = cells
+            else:
+                body.append(cells)
+        i += 1  # table_close
+        self._draw_table(header, body)
+        return i
+
+    @staticmethod
+    def _inline_to_pdf_text(children: list[Token]) -> str:
+        """行内 token → 纯文本（表格单元格用）
+
+        仅保留文本/软换行/硬换行/行内代码/图片 alt；链接取文字、粗斜体
+        标记剥除（表头灰底深色维持加粗观感，不依赖字形切换）。返回文本
+        保证不触发 fpdf2 markdown 解析（`**` 定界符在 CJK 场景会请求
+        未注册的粗体字体名导致崩溃）。
+        """
+        parts: list[str] = []
+        for tok in children:
+            t = tok.type
+            if t == "text":
+                parts.append(tok.content)
+            elif t == "softbreak":
+                parts.append(" ")
+            elif t == "hardbreak":
+                parts.append("\n")
+            elif t in ("code_inline", "image"):
+                parts.append(tok.content or "")
+        return "".join(parts).strip()
+
+    def _draw_table(
+        self, header: list[list[Token]], body: list[list[list[Token]]]
+    ) -> None:
+        """自适应列宽表格：表头灰底加粗、单元格边框换行、撑满页宽
+
+        列宽按内容自适应：优先给每列最长单元文本宽度，总宽不足时按比例
+        缩放，最小列宽保护；行高由 dry_run 预演（markdown 标记参与）得出，
+        保证边框与文字不脱节；跨页时新页重绘表头。
+        """
+        pdf = self.pdf
+        if not header:
+            return
+        ncols = len(header)
+        rows: list[tuple[bool, list[list[Token]]]] = [(True, header)]
+        rows.extend((False, r) for r in body)
+        # --- 列宽分配：按内容自适应（表头 + 全部数据行）---
+        avail = pdf.w - pdf.l_margin - pdf.r_margin
+        pdf.set_font(self._family, "", self._TABLE_SIZE)
+        # 最小列宽保护：至少容纳 4 个全角字符（防长文列被压成一字一行
+        # 竖排）；列数过多时以页宽均分为上限
+        min_col_w = min(pdf.get_string_width("中" * 4) + 2.4, avail / ncols)
+        widths: list[float] = []
+        for ci in range(ncols):
+            max_w = min_col_w
+            for is_head, row in rows:
+                if ci < len(row) and row[ci]:
+                    marked = self._inline_to_pdf_text(row[ci])
+                    max_w = max(max_w, pdf.get_string_width(marked))
+            widths.append(max_w)
+        total_w = sum(widths)
+        if total_w > avail:
+            scale = avail / total_w
+            widths = [w * scale for w in widths]
+        else:
+            # 富余量按列均摊（保持撑满页宽，列宽更均匀）
+            bonus = (avail - total_w) / ncols
+            widths = [w + bonus for w in widths]
+        # --- 逐行绘制（跨页时新页重绘表头）---
+        for is_head, row in rows:
+            row = row + [[]] * (ncols - len(row))
+            # 行高预演：dry_run 折行行数 → 行高
+            row_lines: list[int] = []
+            for ci, cell in enumerate(row):
+                marked = self._inline_to_pdf_text(cell)
+                pdf.set_font(self._family, "", self._TABLE_SIZE)
+                out = pdf.multi_cell(
+                    widths[ci] - 2.4,
+                    5,
+                    marked,
+                    markdown=False,
+                    dry_run=True,
+                    output="LINES",
+                )
+                row_lines.append(len(out) if isinstance(out, list) else 1)
+            row_h = max(row_lines) * 5 + 2.4 if row_lines else 8
+            # 本页放不下（且当前不在页首）→ 翻页；非表头行翻页后重绘表头
+            if (
+                pdf.get_y() + row_h > pdf.h - self._BOTTOM_LIMIT
+                and pdf.get_y() > pdf.t_margin
+            ):
+                pdf.add_page()
+                if not is_head:
+                    self._draw_table_header(header, widths, avail)
+            y0 = pdf.get_y()
+            # 表头灰底整行填充
+            if is_head:
+                pdf.set_fill_color(*self._HEAD_BG_COLOR)
+                pdf.rect(pdf.l_margin, y0, avail, row_h, "F")
+            # 边框 + 单元格内容
+            pdf.set_draw_color(*self._BORDER_COLOR)
+            pdf.set_line_width(0.2)
+            x0 = pdf.l_margin
+            for ci, cell in enumerate(row):
+                pdf.rect(x0, y0, widths[ci], row_h)
+                marked = self._inline_to_pdf_text(cell)
+                pdf.set_xy(x0 + 1.2, y0 + 0.8)
+                pdf.set_font(self._family, "", self._TABLE_SIZE)
+                pdf.multi_cell(widths[ci] - 2.4, 5, marked, markdown=False)
+                x0 += widths[ci]
+            pdf.set_y(y0 + row_h)
+        pdf.ln(3)
+
+    def _draw_table_header(
+        self,
+        header: list[list[Token]],
+        widths: list[float],
+        avail: float,
+    ) -> None:
+        """跨页后在新页顶部重绘表头（灰底加粗）"""
+        pdf = self.pdf
+        y0 = pdf.get_y()
+        row_lines: list[int] = []
+        for ci, cell in enumerate(header):
+            marked = self._inline_to_pdf_text(cell)
+            pdf.set_font(self._family, "", self._TABLE_SIZE)
+            out = pdf.multi_cell(
+                widths[ci] - 2.4,
+                5,
+                marked,
+                markdown=False,
+                dry_run=True,
+                output="LINES",
+            )
+            row_lines.append(len(out) if isinstance(out, list) else 1)
+        row_h = max(row_lines) * 5 + 2.4 if row_lines else 8
+        pdf.set_fill_color(*self._HEAD_BG_COLOR)
+        pdf.rect(pdf.l_margin, y0, avail, row_h, "F")
+        pdf.set_draw_color(*self._BORDER_COLOR)
+        pdf.set_line_width(0.2)
+        x0 = pdf.l_margin
+        for ci, cell in enumerate(header):
+            pdf.rect(x0, y0, widths[ci], row_h)
+            marked = self._inline_to_pdf_text(cell)
+            pdf.set_xy(x0 + 1.2, y0 + 0.8)
+            pdf.set_font(self._family, "", self._TABLE_SIZE)
+            pdf.multi_cell(widths[ci] - 2.4, 5, marked, markdown=False)
+            x0 += widths[ci]
+        pdf.set_y(y0 + row_h)
+
+
+def _pdf_render_markdown(md_text: str, dest: Path, mainfont: str) -> None:
+    """markdown-it token 流驱动 fpdf2 渲染 Markdown 为 PDF（与 HTML 同源解析）
+
+    - 解析：MarkdownIt(commonmark)+table，与 convert_md_to_html（PiMD 内部
+      同为 markdown-it）结构理解一致；支持标题、嵌套列表（有序/无序）、
+      引用块、围栏代码块、GFM 表格、分隔线，及行内粗体/斜体/行内代码/
+      链接/图片 alt 文本。
+    - PDF/A 不可用于中文：PiMD 内置 PDF 引擎为 fpdf2 文本提取（Helvetica），
+      不支持 CJK；本渲染器按 mainfont 注册系统 CJK 字体（B/I/BI 同文件
+      注册，未注册样式在 set_font 时直接抛错），保证中文完整落盘。
+    - 布局对齐 convert_md_to_html 的宽版式观感：A4 纵向、正文 11pt、
+      h1~h6 分级加粗、表格撑满页宽表头灰底、引用块左竖线灰字、链接蓝色。
+    """
+    font_path, font_key = _fpdf_font_key(mainfont)
+    if font_path is None:
+        logger.warning(
+            f"未找到中文字体（mainfont={mainfont}），"
+            "PDF 将使用 Helvetica（仅 ASCII 可读）"
+        )
+
+    pdf = FPDF(format="A4")
+    pdf.set_auto_page_break(auto=True, margin=20)
+    pdf.add_page()
+    if font_path is not None:
+        # Unicode 中文字体无真实粗/斜变体：B/I/BI 均注册同一字形
+        for style in ("", "B", "I", "BI"):
+            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)
+    pdf.output(str(dest))
+
+
+def _is_table_row(line: str) -> bool:
+    """GFM 表格数据行：以竖线开头/结尾，或含 ` | ` 分隔的多列（单列表格
+    仅两端各一条竖线，不能按中间竖线判定）"""
+    s = line.strip()
+    if not s:
+        return False
+    return s.startswith("|") or s.endswith("|") or " | " in s
+
+
+@dataclass(frozen=True, slots=True)
+class ConvertResult:
+    """文档转换结果对象
+
+    由 DocKit.convert 返回，将成功与失败信息统一封装，调用方无需 try/except。
+
+    Attributes:
+        success: 转换是否成功
+        markdown: 转换后的 Markdown 文本，失败时为空字符串
+        file_path: 源文件的绝对路径
+        source_format: anydoc 检测到的规范格式名（如 'docx'、'pdf'），无法检测为 None
+        error: 失败原因描述（异常类型与信息），成功时为 None
+    """
+
+    success: bool
+    markdown: str
+    file_path: str
+    source_format: str | None = None
+    error: str | None = None
+
+
+class DocKit:
+    """文档转换工具类，基于 anydoc 将各类文档转为 Markdown
+
+    支持 Word（.doc/.docx）、PowerPoint（.ppt/.pptx）、Excel（.xls/.xlsx）、
+    CSV、PDF 共 5 类 8 种扩展名，统一输出 GitHub-Flavored Markdown。
+
+    使用方式：
+        # 1. 直接转换（异常向上抛出）
+        markdown = DocKit.convert_to_md("report.docx")
+
+        # 2. 安全转换（返回状态结果，不抛异常）
+        result = DocKit.convert("report.pdf")
+        if result.success:
+            print(result.markdown)
+
+        # 3. 转换并写入 .md 文件
+        DocKit.convert_to_file("report.docx", "out/report.md")
+
+        # 4. 字节内容转换（无需落盘）
+        md = DocKit.convert_bytes_to_md(file_bytes, "csv")
+
+        # 5. Markdown 转 PDF（基于本模块内嵌 fpdf2 渲染器，支持中文）
+        DocKit.convert_md_to_pdf("report.md")                # 同目录 report.pdf
+        DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")
+
+        # 6. Markdown 转 Word（基于 PiMD 默认主题 + 表格撑满后处理）
+        DocKit.convert_md_to_docx("report.md")                # 同目录 report.docx
+        DocKit.convert_md_to_docx("report.md", "out.docx", generate_toc=True)
+
+        # 7. Markdown 转 HTML（基于 PiMD + 宽版式样式注入）
+        DocKit.convert_md_to_html("report.md")               # 同目录 report.html
+        DocKit.convert_md_to_html("report.md", title="项目报告")
+
+    注意：convert_md_to_pdf 为**实验性/内部使用，不提供对外服务**（见
+    convert_md_to_pdf 方法说明）；需要 PDF 时优先用 convert_md_to_html
+    后在浏览器中打印/另存 PDF，或 convert_md_to_docx 后在 Word 中另存 PDF。
+
+    可与 FileKit 组合使用以访问 FILE_STORAGE_ROOT 下的相对路径文件：
+        full_path = FileKit.get_full_path("docs/report.docx")
+        markdown = DocKit.convert_to_md(full_path)
+    """
+
+    SUPPORTED_EXTENSIONS: frozenset[str] = _SUPPORTED_EXTENSIONS
+
+    @staticmethod
+    def is_supported(file_path: str | Path) -> bool:
+        """检查文件格式是否受支持
+
+        Args:
+            file_path: 文件路径（仅依据扩展名判断）
+
+        Returns:
+            bool: 扩展名在支持列表中返回 True
+
+        Example:
+            >>> DocKit.is_supported("report.docx")
+            True
+            >>> DocKit.is_supported("photo.png")
+            False
+        """
+        ext = Path(file_path).suffix.lower()
+        return ext in DocKit.SUPPORTED_EXTENSIONS
+
+    @staticmethod
+    def detect_format(file_path: str | Path) -> str | None:
+        """检测文档的 anydoc 规范格式名称
+
+        通过文件扩展名推断规范格式（如 .pptm → 'pptx'，.docx → 'docx'）。
+        无法识别的扩展名返回 None。
+
+        Args:
+            file_path: 文件路径
+
+        Returns:
+            str | None: 规范格式名称，无法识别返回 None
+
+        Example:
+            >>> DocKit.detect_format("slides.pptm")
+            'pptx'
+        """
+        return anydoc.format_from_path(str(Path(file_path)))
+
+    @staticmethod
+    def convert_to_md(file_path: str | Path) -> str:
+        """将文档文件转换为 Markdown 文本（核心转换方法）
+
+        基于 anydoc，读取本地文件并转换为 GitHub-Flavored Markdown。
+        文本型 PDF 可直接转换；加密、图片型 PDF 等无法转换的情况会抛出异常。
+
+        Args:
+            file_path: 文档文件路径（支持 str 或 Path）
+
+        Returns:
+            str: 转换后的 Markdown 文本
+
+        Raises:
+            FileNotFoundError: 文件不存在
+            ValueError: 文件不是常规文件或格式不受支持
+            anydoc.ConvertError: 文档转换失败（加密、损坏、格式异常等子类）
+            OSError: 文件读取失败
+
+        Example:
+            >>> markdown = DocKit.convert_to_md("report.docx")
+            >>> print(markdown[:100])
+        """
+        path = Path(file_path).resolve()
+
+        if not path.exists():
+            raise FileNotFoundError(f"文件不存在: {path}")
+        if not path.is_file():
+            raise ValueError(f"路径不是有效文件: {path}")
+        if not DocKit.is_supported(path):
+            raise ValueError(
+                f"不支持的文件格式: {path.suffix or '<无扩展名>'}，"
+                f"支持的格式: {', '.join(sorted(DocKit.SUPPORTED_EXTENSIONS))}"
+            )
+
+        logger.info(f"开始转换文档: {path.name}")
+        try:
+            markdown = anydoc.to_markdown(str(path))
+        except anydoc.ConvertError as e:
+            logger.error(f"文档转换失败: {path.name}（{type(e).__name__}）: {e}")
+            raise
+        except OSError as e:
+            logger.error(f"文件读取失败: {path.name}: {e}")
+            raise
+
+        logger.info(f"✅ 文档转换成功: {path.name}（{len(markdown)} 字符）")
+        return markdown
+
+    @staticmethod
+    def convert_bytes_to_md(data: bytes, fmt: str | None = None) -> str:
+        """将文件字节内容转换为 Markdown 文本
+
+        适用于从网络、数据库等渠道获取的字节数据，无需落盘即可转换。
+        格式默认从内容自动检测；CSV 等无特征格式需通过 fmt 显式指定。
+
+        Args:
+            data: 文档文件的字节内容
+            fmt: 显式指定的规范格式名称（如 'csv'），None 时自动检测
+
+        Returns:
+            str: 转换后的 Markdown 文本
+
+        Raises:
+            TypeError: data 不是字节类型
+            ValueError: fmt 指定了不支持的格式名称
+            anydoc.ConvertError: 文档转换失败
+
+        Example:
+            >>> with open("data.csv", "rb") as f:
+            ...     md = DocKit.convert_bytes_to_md(f.read(), "csv")
+            >>> md = DocKit.convert_bytes_to_md(file_bytes)  # 自动检测
+        """
+        if not isinstance(data, (bytes, bytearray)):
+            raise TypeError(f"data 必须为字节类型，当前类型: {type(data).__name__}")
+
+        try:
+            if fmt is not None:
+                # fmt 为任意合法格式名，anydoc 内部会校验；stub 将其限定为
+                # Literal 联合，此处运行时由 anydoc 兜底校验。
+                return anydoc.to_markdown_bytes(bytes(data), fmt)  # type: ignore[arg-type]
+            return anydoc.to_markdown_bytes(bytes(data))
+        except anydoc.ConvertError as e:
+            logger.error(f"字节内容转换失败（{type(e).__name__}）: {e}")
+            raise
+
+    @staticmethod
+    def convert(file_path: str | Path) -> ConvertResult:
+        """安全转换文档为 Markdown，返回包含状态的结果对象
+
+        与 convert_to_md 不同，本方法不抛出异常，而是将成功/失败信息
+        封装到 ConvertResult 中，便于批量处理或状态检查。
+
+        Args:
+            file_path: 文档文件路径
+
+        Returns:
+            ConvertResult: 转换结果，包含 success/markdown/file_path/source_format/error
+
+        Example:
+            >>> result = DocKit.convert("report.pdf")
+            >>> if result.success:
+            ...     print(result.markdown[:100])
+            ... else:
+            ...     print(f"转换失败: {result.error}")
+        """
+        path = Path(file_path).resolve()
+        source_format = DocKit.detect_format(path)
+
+        try:
+            markdown = DocKit.convert_to_md(path)
+        except (FileNotFoundError, ValueError, anydoc.ConvertError, OSError) as e:
+            logger.warning(f"文档转换失败: {path.name}（{type(e).__name__}）: {e}")
+            return ConvertResult(
+                success=False,
+                markdown="",
+                file_path=str(path),
+                source_format=source_format,
+                error=f"{type(e).__name__}: {e}",
+            )
+
+        return ConvertResult(
+            success=True,
+            markdown=markdown,
+            file_path=str(path),
+            source_format=source_format,
+        )
+
+    @staticmethod
+    def convert_to_file(
+        src_path: str | Path, dest_path: str | Path | None = None
+    ) -> str:
+        """转换文档并将 Markdown 输出到 .md 文件
+
+        Args:
+            src_path: 源文档路径
+            dest_path: 目标 .md 文件路径；None 时使用源文件名同目录加 .md 后缀
+
+        Returns:
+            str: 实际写入的目标文件绝对路径
+
+        Raises:
+            FileNotFoundError: 源文件不存在
+            ValueError: 源文件格式不受支持
+            anydoc.ConvertError: 文档转换失败
+
+        Example:
+            >>> DocKit.convert_to_file("report.docx")  # 生成同目录 report.md
+            >>> DocKit.convert_to_file("report.docx", "out/report.md")
+        """
+        src = Path(src_path).resolve()
+        markdown = DocKit.convert_to_md(src)
+
+        if dest_path is None:
+            dest = src.with_suffix(".md")
+        else:
+            dest = Path(dest_path)
+
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(markdown, encoding="utf-8")
+        logger.info(f"✅ Markdown 已写入: {dest}")
+        return str(dest)
+
+    @staticmethod
+    def convert_md_to_pdf(
+        src_path: str | Path,
+        dest_path: str | Path | None = None,
+        *,
+        mainfont: str = "SimSun",
+    ) -> str:
+        """将 Markdown 文件转换为 PDF 文件（基于本模块内嵌 fpdf2 渲染器）
+
+        ⚠️ **实验性/内部使用，不提供对外服务**：本方法效果受 fpdf2 能力
+        局限（CJK 无真实粗/斜体变体、复杂长表格视觉打折），不保证排版
+        质量，不承诺对外服务。**外部需要 PDF 时请改用以下路径**：
+        - 推荐：`convert_md_to_html(...)` 后在浏览器中打印/另存 PDF；
+        - 或 `convert_md_to_docx(...)` 后在 Word 中另存 PDF。
+        本方法仅供内部试验，效果波动属预期；签名与行为保持稳定（不改不删）。
+
+        PiMD 内置 PDF 引擎（Helvetica 文本提取）不支持中文，故 PDF 由本
+        模块 fpdf2 渲染器直接生成：与 convert_md_to_html 同源解析
+        （markdown-it token 流），渲染效果向 HTML 版对齐——支持标题、
+        嵌套列表（有序/无序）、引用块、表格（表头灰底加粗）、围栏代码块、
+        分隔线及行内粗体/斜体/行内代码/链接；按 mainfont 匹配 Windows
+        系统中文字体并注册为 unicode 子集字体，中文文档默认宋体。
+        排版默认值：A4 纵向、正文 11pt、h1~h6 分级加粗、表格撑满页宽、
+        单元格换行、多页自适应分页。
+
+        转换前自动做 CJK 加粗预处理（详见 convert_md_to_docx）。
+
+        Args:
+            src_path: Markdown 源文件路径（支持 str 或 Path）
+            dest_path: 目标 PDF 路径；None 时使用源文件名同目录加 .pdf 后缀
+            mainfont: 正文字体族名，默认 SimSun（需系统已安装该字体）
+
+        Returns:
+            str: 实际写入的 PDF 文件绝对路径
+
+        Raises:
+            FileNotFoundError: 源文件不存在
+            ValueError: 源文件不是常规文件或扩展名不是 .md
+            OSError: 文件读写失败
+            RuntimeError: PDF 渲染失败
+
+        Example:
+            >>> DocKit.convert_md_to_pdf("report.md")  # 生成同目录 report.pdf
+            >>> DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")
+        """
+        src = Path(src_path).resolve()
+        if not src.exists():
+            raise FileNotFoundError(f"文件不存在: {src}")
+        if not src.is_file():
+            raise ValueError(f"路径不是有效文件: {src}")
+        if src.suffix.lower() != ".md":
+            raise ValueError(
+                "源文件必须是 .md 后缀的 Markdown 文件，"
+                f"当前: {src.suffix or '<无扩展名>'}"
+            )
+
+        if dest_path is None:
+            dest = src.with_suffix(".pdf")
+        else:
+            dest = Path(dest_path)
+
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        logger.info(f"开始转换 Markdown 为 PDF: {src.name}")
+
+        # CJK 加粗预处理；fpdf2 渲染器直接读内存文本，无需落盘临时 md
+        processed = _normalize_cjk_bold(src.read_text(encoding="utf-8"))
+
+        try:
+            _pdf_render_markdown(processed, dest, mainfont)
+        except Exception as e:  # noqa: BLE001 - fpdf2 渲染异常统一包装
+            logger.error(f"PDF 渲染失败: {src.name}: {e}")
+            raise RuntimeError(f"PDF 渲染失败: {src.name}: {e}") from e
+
+        logger.info(f"✅ PDF 生成成功: {dest}")
+        return str(dest)
+
+    @staticmethod
+    def convert_md_to_html(
+        src_path: str | Path,
+        dest_path: str | Path | None = None,
+        *,
+        title: str | None = None,
+    ) -> str:
+        """将 Markdown 文件转换为独立 HTML 文件（基于 PiMD）
+
+        PiMD 输出完整 HTML5 文档（自带 <meta charset> 与默认样式），支持
+        GFM 全部语法；默认不注入页面标题（PiMD 默认无 <title> 标签，源
+        文件名不会出现在头部），页面标题直接使用 Markdown 自身的一级标题，
+        也可通过 title 参数显式指定。
+        默认内嵌宽版式排版样式（_MD_HTML_CSS），替代 PiMD 自带默认样式
+        （body `max-width: 900px` 等）：正文容器放大至 60em 并居中，中文
+        优先字体栈（宋体系/黑体系），表格撑满页宽、表头加粗，适配宽屏阅读。
+
+        转换前自动做 CJK 加粗预处理（详见 convert_md_to_docx）。
+
+        Args:
+            src_path: Markdown 源文件路径（支持 str 或 Path）
+            dest_path: 目标 HTML 路径；None 时使用源文件名同目录加 .html 后缀
+            title: 页面标题；None（默认）表示不注入标题，使用 Markdown 自身
+                一级标题；传入字符串则以此为页面标题
+
+        Returns:
+            str: 实际写入的 HTML 文件绝对路径
+
+        Raises:
+            FileNotFoundError: 源文件不存在
+            ValueError: 源文件不是常规文件或扩展名不是 .md
+            OSError: 文件读写失败
+            RuntimeError: HTML 渲染失败
+
+        Example:
+            >>> DocKit.convert_md_to_html("report.md")  # 生成同目录 report.html
+            >>> DocKit.convert_md_to_html("report.md", title="项目报告")
+        """
+        src = Path(src_path).resolve()
+        if not src.exists():
+            raise FileNotFoundError(f"文件不存在: {src}")
+        if not src.is_file():
+            raise ValueError(f"路径不是有效文件: {src}")
+        if src.suffix.lower() != ".md":
+            raise ValueError(
+                "源文件必须是 .md 后缀的 Markdown 文件，"
+                f"当前: {src.suffix or '<无扩展名>'}"
+            )
+
+        if dest_path is None:
+            dest = src.with_suffix(".html")
+        else:
+            dest = Path(dest_path)
+
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        logger.info(f"开始转换 Markdown 为 HTML: {src.name}")
+
+        # CJK 加粗预处理；临时 md 与源文件同目录，保证相对图片路径仍然可用
+        processed = _normalize_cjk_bold(src.read_text(encoding="utf-8"))
+        tmp_md = src.with_name(f".{src.stem}.pimd-tmp.md")
+        tmp_md.write_text(processed, encoding="utf-8")
+
+        try:
+            _PIMD.convert(tmp_md, "html", str(dest))
+        except ConversionError as e:
+            logger.error(f"HTML 渲染失败: {src.name}: {e}")
+            raise RuntimeError(f"HTML 渲染失败: {src.name}: {e}") from e
+        except OSError as e:  # noqa: BLE001 - 文件读写异常统一包装
+            logger.error(f"HTML 渲染失败: {src.name}: {e}")
+            raise RuntimeError(f"HTML 渲染失败: {src.name}: {e}") from e
+        finally:
+            tmp_md.unlink(missing_ok=True)
+
+        # 转换后注入：PiMD 输出完整 HTML5 文档（自带 <style>），在 </head>
+        # 前插入 _MD_HTML_CSS 覆盖其默认窄栏与配色
+        html = dest.read_text(encoding="utf-8")
+        if title is not None and "</title>" not in html:
+            # PiMD 默认不输出 <title>；显式传 title 时才补写，页面标题
+            # 默认使用 Markdown 自身的一级标题
+            html = html.replace("<head>", f"<head>\n<title>{title}</title>", 1)
+        html = html.replace("</head>", f"{_MD_HTML_CSS}\n</head>", 1)
+        dest.write_text(html, encoding="utf-8")
+
+        logger.info(f"✅ HTML 生成成功: {dest}")
+        return str(dest)
+
+    @staticmethod
+    def convert_md_to_docx(
+        src_path: str | Path,
+        dest_path: str | Path | None = None,
+        *,
+        generate_toc: bool = False,
+        mainfont: str = "宋体",
+        reference_doc: str | Path | None = None,
+    ) -> str:
+        """将 Markdown 文件转换为 Word（.docx）文件（基于 PiMD）
+
+        使用 PiMD（markdown-it 解析 + python-docx 渲染，CommonMark 系）
+        生成 docx，支持标题、列表、表格（表头深蓝底加粗）、代码块、链接
+        等语法；可通过 generate_toc 在文档开头插入目录。
+        全文字体统一为 mainfont（默认宋体）：转换后改写 docDefaults 与
+        主题字体（正文/标题/表格全部生效），代码块保持等宽字体；
+        reference_doc 参数仅保留签名兼容（PiMD 的 md_to_docx 不接收参考
+        模板，传入不生效）。
+
+        转换前自动做 CJK 加粗预处理：`**加粗：**后接` 这类闭合 ** 前为
+        全角标点的写法不满足 CommonMark 定界规则（会以字面星号进入
+        Word），内部将其改写为 `**加粗**：后接`，代码块内容不受影响；
+        转换后自动做表格版式后处理（表格撑满页宽并整体居中）。
+
+        Args:
+            src_path: Markdown 源文件路径（支持 str 或 Path）
+            dest_path: 目标 Word 文件路径；None 时使用源文件名同目录加 .docx 后缀
+            generate_toc: 是否在文档开头插入目录
+            mainfont: 文档全局字体名（Word 字体名，如 "宋体"/"黑体"），默认宋体
+            reference_doc: 仅保留签名兼容；PiMD 不接收参考模板，传入不生效
+
+        Returns:
+            str: 实际写入的 Word 文件绝对路径
+
+        Raises:
+            FileNotFoundError: 源文件不存在
+            ValueError: 源文件不是常规文件或扩展名不是 .md
+            OSError: 文件读写失败
+            RuntimeError: Word 渲染失败
+
+        Example:
+            >>> DocKit.convert_md_to_docx("report.md")  # 生成同目录 report.docx
+            >>> DocKit.convert_md_to_docx("report.md", mainfont="仿宋")
+            >>> DocKit.convert_md_to_docx("report.md", "out.docx", generate_toc=True)
+        """
+        src = Path(src_path).resolve()
+        if not src.exists():
+            raise FileNotFoundError(f"文件不存在: {src}")
+        if not src.is_file():
+            raise ValueError(f"路径不是有效文件: {src}")
+        if src.suffix.lower() != ".md":
+            raise ValueError(
+                "源文件必须是 .md 后缀的 Markdown 文件，"
+                f"当前: {src.suffix or '<无扩展名>'}"
+            )
+
+        if dest_path is None:
+            dest = src.with_suffix(".docx")
+        else:
+            dest = Path(dest_path)
+
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        logger.info(f"开始转换 Markdown 为 Word: {src.name}")
+
+        # CJK 加粗预处理；临时 md 与源文件同目录，保证相对图片路径仍然可用
+        processed = _normalize_cjk_bold(src.read_text(encoding="utf-8"))
+        tmp_md = src.with_name(f".{src.stem}.pimd-tmp.md")
+        tmp_md.write_text(processed, encoding="utf-8")
+
+        try:
+            _PIMD.md_to_docx(str(tmp_md), str(dest), generate_toc=generate_toc)
+        except ConversionError as e:
+            logger.error(f"Word 渲染失败: {src.name}: {e}")
+            raise RuntimeError(f"Word 渲染失败: {src.name}: {e}") from e
+        except OSError as e:  # noqa: BLE001 - 文件读写异常统一包装
+            logger.error(f"Word 渲染失败: {src.name}: {e}")
+            raise RuntimeError(f"Word 渲染失败: {src.name}: {e}") from e
+        finally:
+            tmp_md.unlink(missing_ok=True)
+
+        # 表格版式后处理：撑满页宽并整体居中
+        _polish_table_layout(dest)
+        # 全局字体后处理：正文/标题统一为 mainfont（代码块保持等宽）
+        _polish_docx_font(dest, mainfont)
+
+        logger.info(f"✅ Word 生成成功: {dest}")
+        return str(dest)