sdpy-kit 0.4.5__tar.gz → 0.5.1__tar.gz

{sdpy_kit-0.4.5 → sdpy_kit-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.4.5
+Version: 0.5.1
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -32,13 +32,14 @@ Requires-Dist: httpx>=0.28.1; extra == 'all'
 Requires-Dist: huggingface-hub<2,>=1.5; extra == 'all'
 Requires-Dist: laya>=0.4.6; extra == 'all'
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
-Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'all'
+Requires-Dist: marker-pdf>=2.0.0; extra == 'all'
 Requires-Dist: numpy>=2.5.4; extra == 'all'
 Requires-Dist: pikepdf>=10.17.0; extra == 'all'
 Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'all'
 Requires-Dist: psycopg2-binary>=2.9.13; extra == 'all'
 Requires-Dist: pymysql>=1.2.3; extra == 'all'
 Requires-Dist: python-dotenv>=1.2.4; extra == 'all'
+Requires-Dist: rc-docparser>=0.2.2; extra == 'all'
 Requires-Dist: redis>=8.1.0; extra == 'all'
 Requires-Dist: requests>=2.34.2; extra == 'all'
 Requires-Dist: sqliteai-vector>=1.1.2; extra == 'all'
@@ -48,11 +49,13 @@ Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
 Requires-Dist: pikepdf>=10.17.0; extra == 'anydoc'
 Provides-Extra: docx
 Requires-Dist: docxtpl>=0.20.2; extra == 'docx'
+Provides-Extra: docx-parse
+Requires-Dist: rc-docparser>=0.2.2; extra == 'docx-parse'
 Provides-Extra: laya
 Requires-Dist: huggingface-hub<2,>=1.5; extra == 'laya'
 Requires-Dist: laya>=0.4.6; extra == 'laya'
 Provides-Extra: marker
-Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'marker'
+Requires-Dist: marker-pdf>=2.0.0; extra == 'marker'
 Provides-Extra: md2doc
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'md2doc'
 Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'md2doc'
@@ -77,7 +80,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
-- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
+- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
 
 > 要求 Python 3.13+
 
@@ -93,9 +96,10 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
 | `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.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
-| `kit.docs.marker_kit` | `MarkerKit` | 本地文档解析（PDF / 图片 / Office → Markdown + Images） | `marker` |
+| `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
 | `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（两 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
 | `kit.crawl.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
@@ -121,8 +125,9 @@ uv add sdpy-kit
 | `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]"` |
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
-| `marker` | MarkerKit 本地文档解析（marker-pdf[full] → Markdown + Images，依赖体积大） | `pip install "sdpy-kit[marker]"` |
+| `marker` | MarkerKit 本地解析（marker-pdf → Markdown + Images；PDF + 图片，依赖体积大） | `pip install "sdpy-kit[marker]"` |
 | `laya` | LayaKit 类型化决策（laya + torch，本地小模型 choice / score / noul） | `pip install "sdpy-kit[laya]"` |
 | `web-article` | WebArticleKit 通用网页文章抓取转存（trafilatura，纯 HTTP 无浏览器） | `pip install "sdpy-kit[web-article]"` |
 | `all` | 全部能力 | `pip install "sdpy-kit[all]"` |
@@ -871,10 +876,13 @@ md = AnyDocKit.convert_to_md("scan.pdf", ocr="hosted")  # 需 FIRECRAWL_API_KEY
 | `detect_format(file_path) -> str \| None` | 由扩展名推断规范格式名 |
 | `convert_to_md(file_path, *, ocr="reject", api_key=None, api_url=None) -> str` | 文件 → Markdown（非标 PDF 自动修复重试） |
 | `convert_bytes_to_md(data, fmt=None, *, ocr="reject", api_key=None, api_url=None) -> str` | 字节内容 → Markdown |
-| `convert(file_path, *, ocr="reject", api_key=None, api_url=None) -> ConvertResult` | 安全转换 |
+| `convert(file_path, *, ocr="reject", api_key=None, api_url=None) -> AnyDocResult` | 安全转换 |
 | `convert_to_file(src_path, dest_path=None, *, ocr="reject", ...) -> str` | 转换并写入 `.md`，返回目标路径 |
 
-`ConvertResult(success, markdown, file_path, source_format, error)`
+`AnyDocResult(success, markdown, file_path, source_format, error)`
+
+> 异常：沿用上游 `anydoc.ConvertError` 体系（`MalformedError` / `NeedsOcrError` 等子类可直接捕获），
+> `AnyDocError` 是该基类的别名；安全版 `convert()` 会把它们封装为 `AnyDocResult.error`。
 
 ---
 
@@ -971,9 +979,12 @@ if r.state == "done":
 
 ---
 
-## kit.docs.marker_kit —— 本地文档解析（Markdown + Images）
+## kit.docs.marker_kit —— 本地解析：PDF + 图片 → Markdown + Images
+
+安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf`，含 torch 等 80+ 包，体积较大；不含 `[full]`）
 
-安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf[full]`，含 torch 等 80+ 包，体积较大）
+支持面：`.pdf`、`.png`、`.jpg`、`.jpeg`、`.webp`、`.gif`、`.bmp`。docx/pptx/xlsx/html/epub 不在支持面
+（marker 侧实现依赖 weasyprint/GTK），传入会抛 `ValueError`。
 
 ```python
 from kit.docs.marker_kit import MarkerKit
@@ -990,15 +1001,18 @@ result = MarkerKit.convert("report.pdf", "out/doc")
 if result.success:
     print(result.md_path, len(result.image_paths), result.page_count)
 
-# 跳过 VLM（无需 llama.cpp）
-md = MarkerKit.convert_to_md("scan.pdf", disable_ocr=True)
+# 文本层 PDF 离线抽取（跳过 VLM/OCR，无需 llama-server）
+md = MarkerKit.convert_to_md("report.pdf", disable_ocr=True)
+
+# 图片输入（无文本层，必须 OCR：仅 disable_ocr=True 时无文字内容）
+md = MarkerKit.convert_to_md("figure.png", disable_ocr=True)
 
 MarkerKit.shutdown()   # 释放模型与推理服务（幂等）
 ```
 
 | 方法 | 说明 |
 |------|------|
-| `is_supported(file_path) -> bool` | 扩展名白名单（pdf / 图片 / docx / pptx / xlsx / html / epub） |
+| `is_supported(file_path) -> bool` | 白名单：`.pdf` + `.png/.jpg/.jpeg/.webp/.gif/.bmp` |
 | `convert_to_md(file_path, *, mode=None, force_ocr=None, disable_ocr=None, page_range=None) -> str` | 解析并返回 Markdown 文本（图片不落盘） |
 | `convert_to_dir(src_path, output_dir=None, *, mode=None, force_ocr=None, disable_ocr=None, page_range=None, extract_images=True) -> str` | 解析并落盘 md + `images/`，返回 md 绝对路径 |
 | `convert(src_path, output_dir=None, *, ...) -> MarkerResult` | 安全版：失败封装为 `MarkerResult`，不抛异常 |
@@ -1007,7 +1021,36 @@ MarkerKit.shutdown()   # 释放模型与推理服务（幂等）
 > 产物：`<output_dir>/<源文件名>.md` + `<output_dir>/images/`（md 内以 `images/<文件名>` 相对引用；无图片不建空目录），**不生成** `_meta.json`。
 > 结果类型：`MarkerResult`（`success` / `markdown` / `file_path` / `output_dir` / `md_path` / `image_paths` / `page_count` / `error`）；异常：`MarkerError`。
 > `mode` 缺省时不写入配置，交由 marker 按设备自动选择；首次使用会下载模型权重（默认走 `MARKER_HF_ENDPOINT` 镜像）。
-> 非 NVIDIA 平台完整 VLM 能力（公式 / 扫描页 OCR）需 llama.cpp 的 `llama-server`，否则用 `disable_ocr=True` 跳过。
+> **前提条件**：文本层 PDF 传 `disable_ocr=True` 即可完全离线（无需 llama-server）；不传时 marker 默认启用 VLM/OCR，
+> 缺 `llama-server` 抛 `SpawnError`。扫描件 / 图片型 PDF / 图片输入要得到文字，必须有 llama.cpp 的 `llama-server`
+> （`MARKER_LLAMA_CPP_BINARY`），否则只得到空 md 或一条整图引用。PDF 内嵌图片抽取不需要 `llama-server`。
+
+## kit.docs.rc_docparser_kit —— 离线 docx → Markdown + Images
+
+安装：`pip install "sdpy-kit[docx-parse]"`（依赖 `rc-docparser`，纯 Python，无模型 / OCR / GTK）
+
+支持面：仅 `.docx`。产物与 `MarkerKit` 同一契约：`<out>/<stem>.md` + `<out>/images/`。
+
+```python
+from kit.docs.rc_docparser_kit import RcDocParserKit
+
+md_path = RcDocParserKit.convert_to_dir("report.docx")   # -> report/report.md + report/images/
+md = RcDocParserKit.convert_to_md("report.docx")         # 只取文本（图片不落盘）
+result = RcDocParserKit.convert("report.docx", "out/doc")
+if result.success:
+    print(result.md_path, len(result.image_paths))
+```
+
+| 方法 | 说明 |
+|------|------|
+| `is_supported(file_path) -> bool` | 是否 `.docx` |
+| `convert_to_md(file_path) -> str` | 解析并返回 Markdown 文本 |
+| `convert_to_dir(src_path, output_dir=None, *, extract_images=True) -> str` | 落盘 md + `images/`，返回 md 绝对路径 |
+| `convert(src_path, output_dir=None, *, ...) -> RcDocParserResult` | 安全版：失败封装为结果对象 |
+
+> 产物：`<out>/images/img-NNN-<sha1 前 10>.<ext>`（按出现顺序、内容哈希命名）；无图不建空目录。
+> 前提：中文标题依赖 `w:outlineLvl` 或「标题 N」样式（都没有时退化为正文）；合并单元格表格会重建为
+> 等宽 GFM（覆盖位留空，不输出 HTML `<table>`）；页眉页脚/脚注不提取。纯本地，无需模型或 GPU。
 
 ## kit.crawl.wx_article_kit —— 微信公众号文章抓取存储
 

{sdpy_kit-0.4.5 → sdpy_kit-0.5.1}/README.md

@@ -4,7 +4,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
-- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
+- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
 
 > 要求 Python 3.13+
 
@@ -20,9 +20,10 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
 | `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.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
-| `kit.docs.marker_kit` | `MarkerKit` | 本地文档解析（PDF / 图片 / Office → Markdown + Images） | `marker` |
+| `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
 | `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（两 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
 | `kit.crawl.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
@@ -48,8 +49,9 @@ uv add sdpy-kit
 | `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]"` |
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
-| `marker` | MarkerKit 本地文档解析（marker-pdf[full] → Markdown + Images，依赖体积大） | `pip install "sdpy-kit[marker]"` |
+| `marker` | MarkerKit 本地解析（marker-pdf → Markdown + Images；PDF + 图片，依赖体积大） | `pip install "sdpy-kit[marker]"` |
 | `laya` | LayaKit 类型化决策（laya + torch，本地小模型 choice / score / noul） | `pip install "sdpy-kit[laya]"` |
 | `web-article` | WebArticleKit 通用网页文章抓取转存（trafilatura，纯 HTTP 无浏览器） | `pip install "sdpy-kit[web-article]"` |
 | `all` | 全部能力 | `pip install "sdpy-kit[all]"` |
@@ -798,10 +800,13 @@ md = AnyDocKit.convert_to_md("scan.pdf", ocr="hosted")  # 需 FIRECRAWL_API_KEY
 | `detect_format(file_path) -> str \| None` | 由扩展名推断规范格式名 |
 | `convert_to_md(file_path, *, ocr="reject", api_key=None, api_url=None) -> str` | 文件 → Markdown（非标 PDF 自动修复重试） |
 | `convert_bytes_to_md(data, fmt=None, *, ocr="reject", api_key=None, api_url=None) -> str` | 字节内容 → Markdown |
-| `convert(file_path, *, ocr="reject", api_key=None, api_url=None) -> ConvertResult` | 安全转换 |
+| `convert(file_path, *, ocr="reject", api_key=None, api_url=None) -> AnyDocResult` | 安全转换 |
 | `convert_to_file(src_path, dest_path=None, *, ocr="reject", ...) -> str` | 转换并写入 `.md`，返回目标路径 |
 
-`ConvertResult(success, markdown, file_path, source_format, error)`
+`AnyDocResult(success, markdown, file_path, source_format, error)`
+
+> 异常：沿用上游 `anydoc.ConvertError` 体系（`MalformedError` / `NeedsOcrError` 等子类可直接捕获），
+> `AnyDocError` 是该基类的别名；安全版 `convert()` 会把它们封装为 `AnyDocResult.error`。
 
 ---
 
@@ -898,9 +903,12 @@ if r.state == "done":
 
 ---
 
-## kit.docs.marker_kit —— 本地文档解析（Markdown + Images）
+## kit.docs.marker_kit —— 本地解析：PDF + 图片 → Markdown + Images
+
+安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf`，含 torch 等 80+ 包，体积较大；不含 `[full]`）
 
-安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf[full]`，含 torch 等 80+ 包，体积较大）
+支持面：`.pdf`、`.png`、`.jpg`、`.jpeg`、`.webp`、`.gif`、`.bmp`。docx/pptx/xlsx/html/epub 不在支持面
+（marker 侧实现依赖 weasyprint/GTK），传入会抛 `ValueError`。
 
 ```python
 from kit.docs.marker_kit import MarkerKit
@@ -917,15 +925,18 @@ result = MarkerKit.convert("report.pdf", "out/doc")
 if result.success:
     print(result.md_path, len(result.image_paths), result.page_count)
 
-# 跳过 VLM（无需 llama.cpp）
-md = MarkerKit.convert_to_md("scan.pdf", disable_ocr=True)
+# 文本层 PDF 离线抽取（跳过 VLM/OCR，无需 llama-server）
+md = MarkerKit.convert_to_md("report.pdf", disable_ocr=True)
+
+# 图片输入（无文本层，必须 OCR：仅 disable_ocr=True 时无文字内容）
+md = MarkerKit.convert_to_md("figure.png", disable_ocr=True)
 
 MarkerKit.shutdown()   # 释放模型与推理服务（幂等）
 ```
 
 | 方法 | 说明 |
 |------|------|
-| `is_supported(file_path) -> bool` | 扩展名白名单（pdf / 图片 / docx / pptx / xlsx / html / epub） |
+| `is_supported(file_path) -> bool` | 白名单：`.pdf` + `.png/.jpg/.jpeg/.webp/.gif/.bmp` |
 | `convert_to_md(file_path, *, mode=None, force_ocr=None, disable_ocr=None, page_range=None) -> str` | 解析并返回 Markdown 文本（图片不落盘） |
 | `convert_to_dir(src_path, output_dir=None, *, mode=None, force_ocr=None, disable_ocr=None, page_range=None, extract_images=True) -> str` | 解析并落盘 md + `images/`，返回 md 绝对路径 |
 | `convert(src_path, output_dir=None, *, ...) -> MarkerResult` | 安全版：失败封装为 `MarkerResult`，不抛异常 |
@@ -934,7 +945,36 @@ MarkerKit.shutdown()   # 释放模型与推理服务（幂等）
 > 产物：`<output_dir>/<源文件名>.md` + `<output_dir>/images/`（md 内以 `images/<文件名>` 相对引用；无图片不建空目录），**不生成** `_meta.json`。
 > 结果类型：`MarkerResult`（`success` / `markdown` / `file_path` / `output_dir` / `md_path` / `image_paths` / `page_count` / `error`）；异常：`MarkerError`。
 > `mode` 缺省时不写入配置，交由 marker 按设备自动选择；首次使用会下载模型权重（默认走 `MARKER_HF_ENDPOINT` 镜像）。
-> 非 NVIDIA 平台完整 VLM 能力（公式 / 扫描页 OCR）需 llama.cpp 的 `llama-server`，否则用 `disable_ocr=True` 跳过。
+> **前提条件**：文本层 PDF 传 `disable_ocr=True` 即可完全离线（无需 llama-server）；不传时 marker 默认启用 VLM/OCR，
+> 缺 `llama-server` 抛 `SpawnError`。扫描件 / 图片型 PDF / 图片输入要得到文字，必须有 llama.cpp 的 `llama-server`
+> （`MARKER_LLAMA_CPP_BINARY`），否则只得到空 md 或一条整图引用。PDF 内嵌图片抽取不需要 `llama-server`。
+
+## kit.docs.rc_docparser_kit —— 离线 docx → Markdown + Images
+
+安装：`pip install "sdpy-kit[docx-parse]"`（依赖 `rc-docparser`，纯 Python，无模型 / OCR / GTK）
+
+支持面：仅 `.docx`。产物与 `MarkerKit` 同一契约：`<out>/<stem>.md` + `<out>/images/`。
+
+```python
+from kit.docs.rc_docparser_kit import RcDocParserKit
+
+md_path = RcDocParserKit.convert_to_dir("report.docx")   # -> report/report.md + report/images/
+md = RcDocParserKit.convert_to_md("report.docx")         # 只取文本（图片不落盘）
+result = RcDocParserKit.convert("report.docx", "out/doc")
+if result.success:
+    print(result.md_path, len(result.image_paths))
+```
+
+| 方法 | 说明 |
+|------|------|
+| `is_supported(file_path) -> bool` | 是否 `.docx` |
+| `convert_to_md(file_path) -> str` | 解析并返回 Markdown 文本 |
+| `convert_to_dir(src_path, output_dir=None, *, extract_images=True) -> str` | 落盘 md + `images/`，返回 md 绝对路径 |
+| `convert(src_path, output_dir=None, *, ...) -> RcDocParserResult` | 安全版：失败封装为结果对象 |
+
+> 产物：`<out>/images/img-NNN-<sha1 前 10>.<ext>`（按出现顺序、内容哈希命名）；无图不建空目录。
+> 前提：中文标题依赖 `w:outlineLvl` 或「标题 N」样式（都没有时退化为正文）；合并单元格表格会重建为
+> 等宽 GFM（覆盖位留空，不输出 HTML `<table>`）；页眉页脚/脚注不提取。纯本地，无需模型或 GPU。
 
 ## kit.crawl.wx_article_kit —— 微信公众号文章抓取存储
 

{sdpy_kit-0.4.5 → sdpy_kit-0.5.1}/kit/__init__.py

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

{sdpy_kit-0.4.5 → sdpy_kit-0.5.1}/kit/config/kit_config.py

@@ -89,7 +89,7 @@ class Settings(BaseSettings):
         default=600, ge=10, description="任务轮询总超时（秒），超时抛 MinerUError"
     )
 
-    # Marker 本地文档解析配置（marker-pdf，PDF→Markdown+Images，模型本地运行）
+    # Marker 本地解析配置（marker-pdf，PDF/图片→Markdown+Images，模型本地运行）
     MARKER_MODE: str | None = Field(
         default=None,
         description=(

{sdpy_kit-0.4.5 → sdpy_kit-0.5.1}/kit/docs/__init__.py

@@ -25,7 +25,8 @@ Author: Clark Chang
 - md2doc_kit:  Md2DocKit   Markdown 转 Word/PDF/HTML（pimd，extra: md2doc）
 - docx_kit:    DocxKit     Word 模板动态填充（docxtpl，extra: docx）
 - mineru_kit:  MinerUKit   MinerU 文档解析 API（requests，extra: mineru）
-- marker_kit:  MarkerKit   Marker 本地文档解析（marker-pdf，extra: marker）
+- marker_kit:  MarkerKit   PDF + 图片本地解析（marker-pdf，extra: marker）
+- rc_docparser_kit: RcDocParserKit  离线 docx 解析（rc-docparser，extra: docx-parse）
 
 本 __init__ 不导入任何成员：五个模块均携带重型可选依赖，保持
 `import kit.docs` 在基础安装下零成本可用（对齐 kit.crawl 先例）。

{sdpy_kit-0.4.5 → sdpy_kit-0.5.1}/kit/docs/anydoc_kit.py

@@ -18,21 +18,31 @@ Author: Clark Chang
 """
 
 # date: 2026-09-23
-"""文档解析工具类，基于 anydoc 将各类文档统一转为 Markdown
-
-本模块封装 firecrawl-anydoc（pip 安装名 firecrawl-anydoc，import 名 anydoc），
-将 Word、PowerPoint、Excel、CSV、PDF 格式统一转为 GitHub-Flavored Markdown；
-Markdown → Word/HTML/PDF 的反向转换见 kit.docs.md2doc_kit（Md2DocKit）。
-
-设计要点：
-- 全部使用静态方法提供服务，无内部状态。
-- 低层 convert_to_md 直接抛出异常（与 FileKit 风格一致，便于精确定位）。
-- PDF 兼容性：结构非标但内容完好的 PDF（知网 WebFastLoad 尾部垃圾等）遇
-  MalformedError 时自动 pikepdf 重写修复并重试一次；扫描件可传 ocr="hosted"
-  走云端 OCR（需 FIRECRAWL_API_KEY），默认 reject 行为与 anydoc 一致。
-- 高层 convert 返回 ConvertResult 结果对象，封装成功/失败状态，便于批量处理。
-- 路径参数统一支持 str 与 pathlib.Path；需访问文件的方法（convert_to_md /
-  convert_to_file）内部 resolve 为绝对路径，纯扩展名判断方法不做 resolve。
+"""AnyDocKit —— 文档转 Markdown 工具类（基于 firecrawl-anydoc）
+
+支持面：`.doc` / `.docx` / `.ppt` / `.pptx` / `.xls` / `.xlsx` / `.csv` / `.pdf`
+（白名单为 anydoc 支持面的常用子集）。
+
+实现内容：
+- 全部静态方法、无内部状态；低层 `convert_to_md` 直接抛异常，高层 `convert`
+  返回 `AnyDocResult` 封装成功/失败，便于批量处理。
+- PDF 结构非标（如知网件 `%%EOF` 后附加元数据）遇 `MalformedError` 时，用
+  pikepdf 重写为临时文件后重试一次；扫描页默认 reject，`ocr="hosted"` 走云端 OCR。
+- 路径参数支持 `str` / `Path`；访问文件的方法内部 resolve 为绝对路径，
+  纯扩展名判断方法不做 resolve。
+
+前提条件：
+- 只产出 Markdown 文本，**不产出图片**（需要 `md + images/` 时用 `MarkerKit`
+  或 `RcDocParserKit`）。
+- 云端 OCR 需 `FIRECRAWL_API_KEY`（或显式传 `api_key`）。
+
+依赖：
+- `firecrawl-anydoc`（extra `anydoc`，导入名 `anydoc`）+ `pikepdf`；
+  未安装时导入报错并提示安装命令。
+
+异常：
+- 沿用上游 `anydoc.ConvertError` 体系（不包装，保留 `MalformedError` /
+  `NeedsOcrError` 等子类可捕获性）；`AnyDocError` 是该基类的别名。
 """
 
 import io
@@ -44,12 +54,17 @@ try:
     import anydoc
     import pikepdf
 except ImportError as e:
-    raise ImportError("anydoc_kit 需要可选依赖，请安装：pip install sdpy-kit[anydoc]") from e
+    raise ImportError(
+        "anydoc_kit 需要可选依赖，请安装：pip install sdpy-kit[anydoc]"
+    ) from e
 
 from kit.config.log_config import get_default_logger
 
 logger = get_default_logger(__name__)
 
+# 异常别名：沿用 anydoc 的异常体系，不包装（保留上游子类可捕获性）
+AnyDocError = anydoc.ConvertError
+
 # kit 维护的扩展名白名单（用于本地快速校验与错误提示）。
 # 注意：这是 anydoc 实际支持面的子集——anydoc 另支持 docm / pptm / ppsx / ppsm /
 # xlsm / xlsb / pps / pot / odt / ods / odp / rtf / epub 等。
@@ -139,7 +154,7 @@ def _convert_with_repair(
 
 
 @dataclass(frozen=True, slots=True)
-class ConvertResult:
+class AnyDocResult:
     """文档转换结果对象
 
     由 AnyDocKit.convert 返回，将成功与失败信息统一封装，调用方无需 try/except。
@@ -374,11 +389,11 @@ class AnyDocKit:
         ocr: Literal["reject", "hosted"] = "reject",
         api_key: str | None = None,
         api_url: str | None = None,
-    ) -> ConvertResult:
+    ) -> AnyDocResult:
         """安全转换文档为 Markdown，返回包含状态的结果对象
 
         与 convert_to_md 不同，本方法不抛出转换异常，而是将成功/失败信息
-        封装到 ConvertResult 中，便于批量处理或状态检查。
+        封装到 AnyDocResult 中，便于批量处理或状态检查。
         ocr/api_key/api_url 语义同 convert_to_md（PDF 自动修复对调用方
         透明，失败信息封装在 result.error 中）。
         边界：文件不存在 / 格式不支持 / 转换失败均封装为结果；若 file_path
@@ -391,7 +406,7 @@ class AnyDocKit:
             api_url: 云端 OCR 服务地址；None 时回落 FIRECRAWL_API_URL
 
         Returns:
-            ConvertResult: 转换结果，包含 success/markdown/file_path/source_format/error
+            AnyDocResult: 转换结果，包含 success/markdown/file_path/source_format/error
 
         Example:
             >>> result = AnyDocKit.convert("report.pdf")
@@ -410,7 +425,7 @@ class AnyDocKit:
         except (ValueError, anydoc.ConvertError, OSError) as e:
             # OSError 同时覆盖 FileNotFoundError（文件不存在）与文件读取失败
             logger.warning(f"文档转换失败: {path.name}（{type(e).__name__}）: {e}")
-            return ConvertResult(
+            return AnyDocResult(
                 success=False,
                 markdown="",
                 file_path=str(path),
@@ -418,7 +433,7 @@ class AnyDocKit:
                 error=f"{type(e).__name__}: {e}",
             )
 
-        return ConvertResult(
+        return AnyDocResult(
             success=True,
             markdown=markdown,
             file_path=str(path),

{sdpy_kit-0.4.5 → sdpy_kit-0.5.1}/kit/docs/docx_kit.py

@@ -18,29 +18,28 @@ Author: Clark Chang
 """
 
 # date: 2026-09-14
-"""docx 模板动态填充工具类，基于 docxtpl 实现章节与内容全动态的模板渲染
-
-本模块封装 docxtpl，提供「Word 模板 + 结构化数据 → 成品 docx」的模板填充
-服务：章节数量、层级、标题、正文段落、多级列表、表格全部由运行时数据决定，
-模板只承载版式骨架（封面、页眉页脚、字体、编号绑定）。
-
-与 Md2DocKit 的边界：Md2DocKit 负责格式转换（含 Markdown → Word 整篇渲染），本模块
-负责模板填充，二者互不调用。
-
-设计要点：
-- 混合方案：章节循环由模板中的 ``{%p for %}`` 承载，非文本块（列表/表格）
-  以私有使用区字符组成的 marker 段落承载「位置 + 载荷」，渲染后由 python-docx
-  后处理原位转换，规避 docxtpl 无法表达动态层级与富内容的限制。
-- 章节标题段使用锚点样式（默认 ``DocxSectionTitle``），渲染后按 ``level``
-  重设为 ``Heading N``，使模板自身绑定的 Word 多级列表自动编号生效。
-- 模板渲染开启 ``autoescape``，正文文本中的 ``&`` / ``<`` / ``>`` 不会破坏 XML。
-- 变量值中的控制字符语义沿用 docxtpl 约定：``\\n`` 段内软换行、``\\a`` 新段落。
-- 全静态方法、无模块级可变状态（除常量），线程安全。
-- 路径参数统一支持 str 与 pathlib.Path。
-- 有序列表按「连续组」克隆独立编号定义，避免 Word 把多个列表串成一条编号序列。
-- 模板样式统一：:meth:`DocxKit.unify_font` 统一字体、:meth:`DocxKit.unify_heading_color`
-  统一标题颜色，产物继承模板样式；主标题段由 :meth:`DocxKit.create_template` 的
-  ``title`` 参数生成（居中、加粗）。
+"""DocxKit —— docx 模板动态填充工具类（基于 docxtpl）
+
+支持面：Word 模板（`.docx`）+ 结构化数据 → 成品 docx；章节数量、层级、标题、
+正文段落、多级列表、表格均由运行时数据决定，模板只承载版式骨架。
+
+实现内容：
+- 章节循环由模板中的 ``{%p for %}`` 承载；列表/表格以私有使用区字符组成的 marker
+  段落承载「位置 + 载荷」，渲染后由 python-docx 原位转换，规避 docxtpl 无法表达
+  动态层级与富内容的限制。
+- 章节标题段使用锚点样式（默认 ``DocxSectionTitle``），渲染后按 ``level`` 重设为
+  ``Heading N``，使模板绑定的 Word 多级列表自动编号生效。
+- 有序列表按「连续组」克隆独立编号定义，避免多个列表被 Word 串成一条编号序列。
+- 渲染开启 ``autoescape``；变量值控制字符沿用 docxtpl 约定（``\\n`` 软换行、
+  ``\\a`` 新段落）。
+- 全静态方法、无模块级可变状态；路径参数支持 `str` / `Path`。
+
+前提条件：
+- 模板需保留样式与书签骨架；字体/标题颜色统一由 `unify_font` /
+  `unify_heading_color` 处理，产物继承模板样式。
+
+依赖：
+- `docxtpl` + `python-docx`（extra `docx`）；未安装时导入报错并提示安装命令。
 """
 
 import re

{sdpy_kit-0.4.5 → sdpy_kit-0.5.1}/kit/docs/marker_kit.py

@@ -18,33 +18,32 @@ Author: Clark Chang
 """
 
 # date: 2026-10-09
-"""Marker 本地文档解析工具类，将 PDF 等文档转为 Markdown + Images
-
-本模块基于 marker-pdf（Marker v2.x，https://github.com/datalab-to/marker），
-在本地解析 PDF / 图片 / Office / HTML / EPUB，输出 GitHub-Flavored Markdown
-并提取图片，产物形态为「md + images/」一层（kit 文档解析类工具的统一契约）。
-
-与 kit.docs.anydoc_kit 的分工：
-- AnyDocKit：轻量文本转换（firecrawl-anydoc），只产出 Markdown 文本；
-- MarkerKit：本地模型解析，产出 md + 图片，质量更高但依赖重（torch 等）。
-
-设计要点：
-- 按需加载：依赖 marker-pdf，缺失时导入报错并提示
-  `pip install sdpy-kit[marker]`（可选依赖，不进入基础安装）。
-- 模型进程内单例：create_model_dict 开销极大（首次还要下载权重），
-  由类级缓存 + 线程锁保护；转换过程串行化，避免并发不稳定。
-- 导入 marker 之前先应用 HuggingFace 环境（镜像入口、禁用 Xet），
-  否则国内网络下模型权重下载会超时或挂起。
-- 低层 convert_to_md / convert_to_dir 直接抛出异常（便于精确定位）；
-  高层 convert 返回 MarkerResult 结果对象，便于批量处理。
-- 产物只落盘 md + images，不写 marker 默认的 _meta.json。
-- 日志消息不使用 emoji：Windows 默认 GBK 控制台无法编码 emoji，
-  会使 logging 抛出 UnicodeEncodeError。
-
-使用前准备（非 NVIDIA 平台）：
-- 首次使用会自动下载模型权重（默认走 MARKER_HF_ENDPOINT 镜像）；
-- 完整 VLM 能力（公式/扫描页 OCR）需 llama.cpp 的 llama-server，
-  可通过 MARKER_LLAMA_CPP_BINARY 指定；否则用 disable_ocr=True 跳过 VLM。
+"""MarkerKit —— PDF + 图片本地解析工具类（基于 marker-pdf）
+
+支持面：`.pdf`、`.png`、`.jpg`、`.jpeg`、`.webp`、`.gif`、`.bmp`；其余后缀
+（docx/pptx/xlsx/html/epub 等）抛 `ValueError` 并给出归属指引。
+
+实现内容：
+- 模型进程内单例（`create_model_dict` 开销极大），类级缓存 + 线程锁保护，
+  转换过程串行化，避免 marker 并发不稳定。
+- 低层 `convert_to_md` / `convert_to_dir` 直接抛异常，高层 `convert` 返回
+  `MarkerResult` 封装成功/失败。
+- 产物只落 `md + images/`（不写 marker 默认的 `_meta.json`）；图片统一转 RGB
+  后保存、文件名取 basename 防路径穿越；md 引用改写为 `images/<文件名>`。
+- 导入 marker 之前应用 HuggingFace 环境（镜像入口、禁用 Xet），否则权重下载
+  可能超时或挂起；日志不使用 emoji（Windows GBK 控制台无法编码）。
+
+前提条件：
+- 首次使用会自动下载模型权重（默认走 `MARKER_HF_ENDPOINT` 镜像）。
+- **文本层 PDF**：显式 `disable_ocr=True` 可完全离线转换、无需 llama-server；
+  不传时默认启用 VLM/OCR 链路，缺 llama-server 抛 `SpawnError`。
+- **扫描件 / 图片型 PDF、图片输入**：没有文本层，必须 OCR；marker 的识别模型
+  就是 VLM（由 llama.cpp 的 `llama-server` 承载），缺省时 `disable_ocr=True`
+  得到空正文、默认参数抛 `SpawnError`。
+- **PDF 内嵌图片抽取**（`images/` 产物）：不需要 llama-server，本地模型即可。
+
+依赖：
+- `marker-pdf`（extra `marker`，**不含 `[full]`**）；未安装时导入报错并提示安装命令。
 """
 
 import os
@@ -79,26 +78,19 @@ except ImportError as e:
     ) from e
 
 # kit 维护的扩展名白名单（本地快速校验与错误提示）。
-# 注意：这是 marker 实际支持面的常用子集；marker-pdf[full] 另覆盖 epub/html 等，
-# 未列入的扩展名请在确认 marker 支持后按需增补。
+# 只含 PDF 与图片：marker 对其余格式（docx/pptx/xlsx/html/epub）的实现是「先转 PDF」
+# 且依赖 weasyprint（GTK 系统库），Windows/离线不可用，故不声明（见 0.5.0 方案）。
 _SUPPORTED_EXTENSIONS: frozenset[str] = frozenset(
     {
-        # PDF
+        # PDF（文本层 PDF 用 disable_ocr=True 可离线转换）
         ".pdf",
-        # 图片
+        # 图片（无文本层，必须 OCR：需 llama-server 才能得到正文）
         ".png",
         ".jpg",
         ".jpeg",
         ".webp",
         ".gif",
         ".bmp",
-        # Office（marker-pdf[full]：mammoth / python-pptx / openpyxl）
-        ".docx",
-        ".pptx",
-        ".xlsx",
-        # 网页 / 电子书（marker-pdf[full]：weasyprint / ebooklib）
-        ".html",
-        ".epub",
     }
 )
 
@@ -141,9 +133,9 @@ class MarkerResult:
 
 
 class MarkerKit:
-    """Marker 本地文档解析工具类，将文档转为 Markdown + Images
+    """Marker 本地文档解析工具类，将 PDF / 图片转为 Markdown + Images
 
-    支持 PDF、图片、Office（docx/pptx/xlsx）、HTML、EPUB，产物形态为
+    仅支持 PDF 与图片（png/jpg/jpeg/webp/gif/bmp），产物形态为
     「md + images/」一层（md 以 `images/<文件名>` 相对路径引用图片）。
 
     使用前安装可选依赖::
@@ -164,17 +156,20 @@ class MarkerKit:
         if result.success:
             print(result.md_path, result.image_paths)
 
-        # 4. 纯文本层抽取（跳过 VLM，无需 llama.cpp）
-        md = MarkerKit.convert_to_md("scan.pdf", disable_ocr=True)
+        # 4. 离线纯文本层抽取（跳过 VLM/OCR，无需 llama-server）
+        md = MarkerKit.convert_to_md("report.pdf", disable_ocr=True)
 
         # 5. 进程退出前释放模型
         MarkerKit.shutdown()
 
     注意：
+    - **文本层 PDF**：`disable_ocr=True` 可完全离线转换；不传时 marker 默认启用
+      VLM/OCR 链路，缺 llama-server 会抛 SpawnError。
+    - **扫描件/图片型 PDF、图片输入**：必须 OCR，需 llama.cpp 的 llama-server
+      （MARKER_LLAMA_CPP_BINARY 指定）；缺省时 `disable_ocr=True` 得到空正文、
+      默认参数抛 SpawnError。PDF 内嵌图片抽取不受影响。
     - 默认模式由 MARKER_MODE 决定，未配置时不写 mode，交由 marker 按设备自动
       选择（CUDA→balanced，CPU/MPS→fast）；可用 mode 参数显式覆盖。
-    - 非 NVIDIA 平台完整 VLM 能力需 llama.cpp 的 llama-server，缺失时可通过
-      disable_ocr=True 跳过（公式与扫描页不做 OCR）。
     - 建议串行调用；模型与转换过程由内部锁保护，不做多线程并发转换。
     """
 
@@ -224,6 +219,8 @@ class MarkerKit:
         if not MarkerKit.is_supported(path):
             raise ValueError(
                 f"不支持的文件格式: {path.suffix or '<无扩展名>'}，"
+                f"MarkerKit 仅处理 PDF 与图片"
+                f"（docx/pptx/xlsx/html/epub 已不由本工具处理），"
                 f"支持的格式: {', '.join(sorted(MarkerKit.SUPPORTED_EXTENSIONS))}"
             )
         return path