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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.4.3
+Version: 0.4.5
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -77,7 +77,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 本地解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
 
 > 要求 Python 3.13+
 
@@ -91,11 +91,11 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
 | `kit.file_kit` | `FileKit` | 文件与目录读写、移动、遍历 | 无 |
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
-| `kit.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
-| `kit.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
-| `kit.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML | `md2doc` |
-| `kit.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
-| `kit.marker_kit` | `MarkerKit` | 本地文档解析（PDF / 图片 / Office → Markdown + Images） | `marker` |
+| `kit.docs.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
+| `kit.docs.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
+| `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.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
 | `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（两 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
 | `kit.crawl.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
@@ -180,7 +180,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 ### 环境变量 ↔ 能力对照表
 
-> 表中未出现的模块（`kit.crawl.article_models`、`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`、`kit.crawl.wx_article_kit`、`kit.crawl.web_article_kit`）不读取任何环境变量。
+> 表中未出现的模块（`kit.crawl.article_models`、`kit.common_kit`、`kit.docs.docx_kit`、`kit.docs.md2doc_kit`、`kit.crawl.wx_article_kit`、`kit.crawl.web_article_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -231,7 +231,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `KIT_AI_CHAIN_TIMEOUT` | 未设置 | 全局整链预算（秒）= 门面同步等待上限。⚠ **不是 `Settings` 字段**，由代码直读 `os.environ`，无类型/范围校验，非法值仅告警后回退 |
 | *（密钥，变量名由档案决定）* | 无 | 名字写在 `ai_models.json` 各档案的 `api_key` 字段（如 `SILICONFLOW_API_KEY`），值放 `.env` 或系统环境变量。未配置的档案会被剔除出候选链；该类型全部未配置则调用失败 |
 
-**MinerU** → `kit.mineru_kit`
+**MinerU** → `kit.docs.mineru_kit`
 
 | 环境变量 | 默认值 | 作用 |
 |----------|--------|------|
@@ -242,7 +242,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `MINERU_POLL_INTERVAL` | `2.0`（≥0.5） | 任务轮询间隔 |
 | `MINERU_MAX_WAIT` | `600`（≥10） | 轮询总超时，超时抛 `MinerUError` |
 
-**Marker** → `kit.marker_kit`
+**Marker** → `kit.docs.marker_kit`
 
 | 环境变量 | 默认值 | 作用 |
 |----------|--------|------|
@@ -265,7 +265,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 > `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
 > `LAYA_MODEL` / `LAYA_DEVICE` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
 
-**云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.anydoc_kit`
+**云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.docs.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
 |----------|--------|------|
@@ -295,7 +295,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | 改动内容 | 生效时机 |
 |----------|----------|
 | `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`MINERU_*`、`MARKER_MODE` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
-| `MARKER_HF_ENDPOINT` / `MARKER_HF_DISABLE_XET` / `MARKER_LLAMA_CPP_BINARY` | 仅在 `import kit.marker_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
+| `MARKER_HF_ENDPOINT` / `MARKER_HF_DISABLE_XET` / `MARKER_LLAMA_CPP_BINARY` | 仅在 `import kit.docs.marker_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
 | `LAYA_HF_ENDPOINT` / `LAYA_HF_DISABLE_XET` | 仅在 `import kit.laya_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
 | AI 密钥写在 `.env` 里 | `.env` 只在加载档案时注入一次 → 重启，或 `AI.reload_config(reload_file=True)` |
 | AI 密钥由自己写入 `os.environ` | `AI.reload_config()`（默认 `reload_file=False`，只重读 `os.environ`） |
@@ -849,12 +849,12 @@ CommonKit.format_current_time("yyyy-MM-dd")
 
 ---
 
-## kit.anydoc_kit —— 文档转 Markdown
+## kit.docs.anydoc_kit —— 文档转 Markdown
 
 安装：`pip install "sdpy-kit[anydoc]"`（支持 `.doc .docx .ppt .pptx .xls .xlsx .csv .pdf`）
 
 ```python
-from kit.anydoc_kit import AnyDocKit
+from kit.docs.anydoc_kit import AnyDocKit
 
 markdown = AnyDocKit.convert_to_md("report.docx")     # 直接转换，失败抛异常
 result = AnyDocKit.convert("report.pdf")              # 安全转换，异常封装为结果对象
@@ -878,12 +878,12 @@ md = AnyDocKit.convert_to_md("scan.pdf", ocr="hosted")  # 需 FIRECRAWL_API_KEY
 
 ---
 
-## kit.docx_kit —— Word 模板动态填充
+## kit.docs.docx_kit —— Word 模板动态填充
 
 安装：`pip install "sdpy-kit[docx]"`
 
 ```python
-from kit.docx_kit import DocxKit, DocxReport, DocxSection, DocxParagraph, DocxTable
+from kit.docs.docx_kit import DocxKit, DocxReport, DocxSection, DocxParagraph, DocxTable
 
 DocxKit.create_template("templates/report.docx", title="{{ title }}")   # 生成模板骨架
 DocxKit.unify_font("templates/report.docx", font_name="宋体")
@@ -917,12 +917,12 @@ DocxKit.render("templates/report.docx", "out/report.docx", report)
 
 ---
 
-## kit.md2doc_kit —— Markdown 转 Word / PDF / HTML
+## kit.docs.md2doc_kit —— Markdown 转 Word / PDF / HTML
 
 安装：`pip install "sdpy-kit[md2doc]"`（PDF 需系统已安装 `mainfont` 指定字体，默认 `SimSun`）
 
 ```python
-from kit.md2doc_kit import Md2DocKit
+from kit.docs.md2doc_kit import Md2DocKit
 
 Md2DocKit.convert_md_to_docx("report.md", "out.docx", generate_toc=True)
 Md2DocKit.convert_md_to_html("report.md", title="项目报告")
@@ -939,12 +939,12 @@ Md2DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")
 
 ---
 
-## kit.mineru_kit —— MinerU 文档解析
+## kit.docs.mineru_kit —— MinerU 文档解析
 
 安装：`pip install "sdpy-kit[mineru]"`（精准解析需 `MINERU_API_KEY`，Agent 轻量解析免登录）
 
 ```python
-from kit.mineru_kit import MinerUKit
+from kit.docs.mineru_kit import MinerUKit
 
 # 精准解析：公网 URL / 本地文件
 result = MinerUKit.parse_url("https://cdn-mineru.openxlab.org.cn/demo/example.pdf", model_version="vlm")
@@ -971,15 +971,15 @@ if r.state == "done":
 
 ---
 
-## kit.marker_kit —— 本地文档解析（Markdown + Images）
+## kit.docs.marker_kit —— 本地文档解析（Markdown + Images）
 
 安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf[full]`，含 torch 等 80+ 包，体积较大）
 
 ```python
-from kit.marker_kit import MarkerKit
+from kit.docs.marker_kit import MarkerKit
 
-# 落盘 md + images（推荐）：源文件同目录下建同名子目录
-md_path = MarkerKit.convert_to_dir("report.pdf")              # -> report/report.md + 图片
+# 落盘 md + images/（推荐）：源文件同目录下建同名子目录
+md_path = MarkerKit.convert_to_dir("report.pdf")              # -> report/report.md + report/images/
 md_path = MarkerKit.convert_to_dir("report.pdf", "out/doc")   # 指定产物目录
 
 # 只取 Markdown 文本（图片不落盘）
@@ -1000,11 +1000,11 @@ MarkerKit.shutdown()   # 释放模型与推理服务（幂等）
 |------|------|
 | `is_supported(file_path) -> bool` | 扩展名白名单（pdf / 图片 / docx / pptx / xlsx / html / epub） |
 | `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_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`，不抛异常 |
 | `shutdown() -> None` | 释放模型与共享推理服务（幂等） |
 
-> 产物：`<output_dir>/<源文件名>.md` + 图片文件（md 内相对路径引用），**不生成** `_meta.json`。
+> 产物：`<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` 跳过。

{sdpy_kit-0.4.3 → sdpy_kit-0.4.5}/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 本地解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
 
 > 要求 Python 3.13+
 
@@ -18,11 +18,11 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
 | `kit.file_kit` | `FileKit` | 文件与目录读写、移动、遍历 | 无 |
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
-| `kit.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
-| `kit.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
-| `kit.md2doc_kit` | `Md2DocKit` | Markdown → Word / PDF / HTML | `md2doc` |
-| `kit.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
-| `kit.marker_kit` | `MarkerKit` | 本地文档解析（PDF / 图片 / Office → Markdown + Images） | `marker` |
+| `kit.docs.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
+| `kit.docs.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
+| `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.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
 | `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（两 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
 | `kit.crawl.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
@@ -107,7 +107,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 ### 环境变量 ↔ 能力对照表
 
-> 表中未出现的模块（`kit.crawl.article_models`、`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`、`kit.crawl.wx_article_kit`、`kit.crawl.web_article_kit`）不读取任何环境变量。
+> 表中未出现的模块（`kit.crawl.article_models`、`kit.common_kit`、`kit.docs.docx_kit`、`kit.docs.md2doc_kit`、`kit.crawl.wx_article_kit`、`kit.crawl.web_article_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -158,7 +158,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `KIT_AI_CHAIN_TIMEOUT` | 未设置 | 全局整链预算（秒）= 门面同步等待上限。⚠ **不是 `Settings` 字段**，由代码直读 `os.environ`，无类型/范围校验，非法值仅告警后回退 |
 | *（密钥，变量名由档案决定）* | 无 | 名字写在 `ai_models.json` 各档案的 `api_key` 字段（如 `SILICONFLOW_API_KEY`），值放 `.env` 或系统环境变量。未配置的档案会被剔除出候选链；该类型全部未配置则调用失败 |
 
-**MinerU** → `kit.mineru_kit`
+**MinerU** → `kit.docs.mineru_kit`
 
 | 环境变量 | 默认值 | 作用 |
 |----------|--------|------|
@@ -169,7 +169,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `MINERU_POLL_INTERVAL` | `2.0`（≥0.5） | 任务轮询间隔 |
 | `MINERU_MAX_WAIT` | `600`（≥10） | 轮询总超时，超时抛 `MinerUError` |
 
-**Marker** → `kit.marker_kit`
+**Marker** → `kit.docs.marker_kit`
 
 | 环境变量 | 默认值 | 作用 |
 |----------|--------|------|
@@ -192,7 +192,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 > `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
 > `LAYA_MODEL` / `LAYA_DEVICE` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
 
-**云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.anydoc_kit`
+**云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.docs.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
 |----------|--------|------|
@@ -222,7 +222,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | 改动内容 | 生效时机 |
 |----------|----------|
 | `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`MINERU_*`、`MARKER_MODE` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
-| `MARKER_HF_ENDPOINT` / `MARKER_HF_DISABLE_XET` / `MARKER_LLAMA_CPP_BINARY` | 仅在 `import kit.marker_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
+| `MARKER_HF_ENDPOINT` / `MARKER_HF_DISABLE_XET` / `MARKER_LLAMA_CPP_BINARY` | 仅在 `import kit.docs.marker_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
 | `LAYA_HF_ENDPOINT` / `LAYA_HF_DISABLE_XET` | 仅在 `import kit.laya_kit` 时经 `os.environ.setdefault` 应用 → 改动需**重启进程**重新导入模块 |
 | AI 密钥写在 `.env` 里 | `.env` 只在加载档案时注入一次 → 重启，或 `AI.reload_config(reload_file=True)` |
 | AI 密钥由自己写入 `os.environ` | `AI.reload_config()`（默认 `reload_file=False`，只重读 `os.environ`） |
@@ -776,12 +776,12 @@ CommonKit.format_current_time("yyyy-MM-dd")
 
 ---
 
-## kit.anydoc_kit —— 文档转 Markdown
+## kit.docs.anydoc_kit —— 文档转 Markdown
 
 安装：`pip install "sdpy-kit[anydoc]"`（支持 `.doc .docx .ppt .pptx .xls .xlsx .csv .pdf`）
 
 ```python
-from kit.anydoc_kit import AnyDocKit
+from kit.docs.anydoc_kit import AnyDocKit
 
 markdown = AnyDocKit.convert_to_md("report.docx")     # 直接转换，失败抛异常
 result = AnyDocKit.convert("report.pdf")              # 安全转换，异常封装为结果对象
@@ -805,12 +805,12 @@ md = AnyDocKit.convert_to_md("scan.pdf", ocr="hosted")  # 需 FIRECRAWL_API_KEY
 
 ---
 
-## kit.docx_kit —— Word 模板动态填充
+## kit.docs.docx_kit —— Word 模板动态填充
 
 安装：`pip install "sdpy-kit[docx]"`
 
 ```python
-from kit.docx_kit import DocxKit, DocxReport, DocxSection, DocxParagraph, DocxTable
+from kit.docs.docx_kit import DocxKit, DocxReport, DocxSection, DocxParagraph, DocxTable
 
 DocxKit.create_template("templates/report.docx", title="{{ title }}")   # 生成模板骨架
 DocxKit.unify_font("templates/report.docx", font_name="宋体")
@@ -844,12 +844,12 @@ DocxKit.render("templates/report.docx", "out/report.docx", report)
 
 ---
 
-## kit.md2doc_kit —— Markdown 转 Word / PDF / HTML
+## kit.docs.md2doc_kit —— Markdown 转 Word / PDF / HTML
 
 安装：`pip install "sdpy-kit[md2doc]"`（PDF 需系统已安装 `mainfont` 指定字体，默认 `SimSun`）
 
 ```python
-from kit.md2doc_kit import Md2DocKit
+from kit.docs.md2doc_kit import Md2DocKit
 
 Md2DocKit.convert_md_to_docx("report.md", "out.docx", generate_toc=True)
 Md2DocKit.convert_md_to_html("report.md", title="项目报告")
@@ -866,12 +866,12 @@ Md2DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")
 
 ---
 
-## kit.mineru_kit —— MinerU 文档解析
+## kit.docs.mineru_kit —— MinerU 文档解析
 
 安装：`pip install "sdpy-kit[mineru]"`（精准解析需 `MINERU_API_KEY`，Agent 轻量解析免登录）
 
 ```python
-from kit.mineru_kit import MinerUKit
+from kit.docs.mineru_kit import MinerUKit
 
 # 精准解析：公网 URL / 本地文件
 result = MinerUKit.parse_url("https://cdn-mineru.openxlab.org.cn/demo/example.pdf", model_version="vlm")
@@ -898,15 +898,15 @@ if r.state == "done":
 
 ---
 
-## kit.marker_kit —— 本地文档解析（Markdown + Images）
+## kit.docs.marker_kit —— 本地文档解析（Markdown + Images）
 
 安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf[full]`，含 torch 等 80+ 包，体积较大）
 
 ```python
-from kit.marker_kit import MarkerKit
+from kit.docs.marker_kit import MarkerKit
 
-# 落盘 md + images（推荐）：源文件同目录下建同名子目录
-md_path = MarkerKit.convert_to_dir("report.pdf")              # -> report/report.md + 图片
+# 落盘 md + images/（推荐）：源文件同目录下建同名子目录
+md_path = MarkerKit.convert_to_dir("report.pdf")              # -> report/report.md + report/images/
 md_path = MarkerKit.convert_to_dir("report.pdf", "out/doc")   # 指定产物目录
 
 # 只取 Markdown 文本（图片不落盘）
@@ -927,11 +927,11 @@ MarkerKit.shutdown()   # 释放模型与推理服务（幂等）
 |------|------|
 | `is_supported(file_path) -> bool` | 扩展名白名单（pdf / 图片 / docx / pptx / xlsx / html / epub） |
 | `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_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`，不抛异常 |
 | `shutdown() -> None` | 释放模型与共享推理服务（幂等） |
 
-> 产物：`<output_dir>/<源文件名>.md` + 图片文件（md 内相对路径引用），**不生成** `_meta.json`。
+> 产物：`<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` 跳过。

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

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

sdpy_kit-0.4.5/kit/docs/__init__.py

@@ -0,0 +1,32 @@
+"""
+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-10-16
+"""文档格式转换子包——文档解析 / 渲染 / 模板填充工具集
+
+成员（均按需 import，各自绑定独立 extras，缺依赖时模块顶层报错并提示安装命令）：
+- anydoc_kit:  AnyDocKit   文档转 Markdown（firecrawl-anydoc，extra: anydoc）
+- 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）
+
+本 __init__ 不导入任何成员：五个模块均携带重型可选依赖，保持
+`import kit.docs` 在基础安装下零成本可用（对齐 kit.crawl 先例）。
+"""

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

@@ -22,7 +22,7 @@ Author: Clark Chang
 
 本模块封装 firecrawl-anydoc（pip 安装名 firecrawl-anydoc，import 名 anydoc），
 将 Word、PowerPoint、Excel、CSV、PDF 格式统一转为 GitHub-Flavored Markdown；
-Markdown → Word/HTML/PDF 的反向转换见 kit.md2doc_kit（Md2DocKit）。
+Markdown → Word/HTML/PDF 的反向转换见 kit.docs.md2doc_kit（Md2DocKit）。
 
 设计要点：
 - 全部使用静态方法提供服务，无内部状态。
@@ -183,7 +183,7 @@ class AnyDocKit:
         # 5. 字节内容转换（无需落盘）
         md = AnyDocKit.convert_bytes_to_md(file_bytes, "csv")
 
-    Markdown → Word/PDF/HTML 的反向转换见 kit.md2doc_kit（Md2DocKit）。
+    Markdown → Word/PDF/HTML 的反向转换见 kit.docs.md2doc_kit（Md2DocKit）。
 
     可与 FileKit 组合使用以访问 FILE_STORAGE_ROOT 下的相对路径文件：
         full_path = FileKit.get_full_path("docs/report.docx")

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

@@ -22,9 +22,9 @@ Author: Clark Chang
 
 本模块基于 marker-pdf（Marker v2.x，https://github.com/datalab-to/marker），
 在本地解析 PDF / 图片 / Office / HTML / EPUB，输出 GitHub-Flavored Markdown
-并提取图片，产物形态对齐 kit.mineru_kit 的「md + images」。
+并提取图片，产物形态为「md + images/」一层（kit 文档解析类工具的统一契约）。
 
-与 kit.anydoc_kit 的分工：
+与 kit.docs.anydoc_kit 的分工：
 - AnyDocKit：轻量文本转换（firecrawl-anydoc），只产出 Markdown 文本；
 - MarkerKit：本地模型解析，产出 md + 图片，质量更高但依赖重（torch 等）。
 
@@ -125,7 +125,7 @@ class MarkerResult:
         file_path: 源文件绝对路径
         output_dir: 产物目录绝对路径；未落盘时为 None
         md_path: 落盘的 Markdown 文件绝对路径；未落盘时为 None
-        image_paths: 落盘的图片文件绝对路径元组
+        image_paths: 落盘的图片文件绝对路径元组（位于 `<output_dir>/images/`）
         page_count: 文档页数，未知为 None
         error: 失败原因描述（异常类型与信息），成功时为 None
     """
@@ -143,8 +143,8 @@ class MarkerResult:
 class MarkerKit:
     """Marker 本地文档解析工具类，将文档转为 Markdown + Images
 
-    支持 PDF、图片、Office（docx/pptx/xlsx）、HTML、EPUB，产物形态对齐
-    kit.mineru_kit（md + 图片落盘于同一目录，md 以相对路径引用图片）。
+    支持 PDF、图片、Office（docx/pptx/xlsx）、HTML、EPUB，产物形态为
+    「md + images/」一层（md 以 `images/<文件名>` 相对路径引用图片）。
 
     使用前安装可选依赖::
 
@@ -322,7 +322,25 @@ class MarkerKit:
         return Path(output_dir).resolve()
 
     @staticmethod
+    def _localize_image_refs(markdown: str, mapping: dict[str, str]) -> str:
+        """把 md 中的裸图片文件名引用改写为 `images/` 相对路径
+
+        Args:
+            markdown: marker 输出的 Markdown 原文
+            mapping: 原文件名 → 改写后的相对路径（如 `_page_0_Figure_1.jpeg`
+                → `images/_page_0_Figure_1.jpeg`）
+
+        Returns:
+            str: 改写后的 Markdown
+        """
+        for original, rel in mapping.items():
+            markdown = markdown.replace(f"]({original})", f"]({rel})")
+            markdown = markdown.replace(f'src="{original}"', f'src="{rel}"')
+        return markdown
+
+    @classmethod
     def _write_outputs(
+        cls,
         src: Path,
         out_dir: Path,
         markdown: str,
@@ -332,18 +350,25 @@ class MarkerKit:
     ) -> tuple[str, tuple[str, ...]]:
         """落盘 Markdown 与图片，返回 (md 路径, 图片路径元组)
 
+        产物为 `<out_dir>/<源文件名>.md` + `<out_dir>/images/` 图片目录，
+        md 内以 `images/<文件名>` 相对引用；无图片时不创建空 `images/`。
         图片名取 basename 防路径穿越；统一转 RGB 后再存（RGBA 存 JPEG 会失败）。
         """
         out_dir.mkdir(parents=True, exist_ok=True)
-        md_path = out_dir / f"{src.stem}.md"
-        md_path.write_text(markdown, encoding="utf-8")
-
         image_paths: list[str] = []
         if extract_images:
+            images_dir = out_dir / "images"
+            mapping: dict[str, str] = {}
             for name, image in images.items():
-                target = out_dir / Path(name).name
+                target = images_dir / Path(name).name
+                target.parent.mkdir(parents=True, exist_ok=True)
                 image.convert("RGB").save(target)
+                mapping[target.name] = f"images/{target.name}"
                 image_paths.append(str(target))
+            markdown = cls._localize_image_refs(markdown, mapping)
+
+        md_path = out_dir / f"{src.stem}.md"
+        md_path.write_text(markdown, encoding="utf-8")
         return str(md_path), tuple(image_paths)
 
     # ------------------------------------------------------------------
@@ -410,7 +435,8 @@ class MarkerKit:
     ) -> str:
         """解析文档并将 Markdown + 图片落盘到目录
 
-        产物写入 output_dir：`<源文件名>.md` 与若干图片文件（md 以相对路径引用）。
+        产物写入 output_dir：`<源文件名>.md` 与 `images/` 图片目录（md 内以
+        `images/<文件名>` 相对路径引用）；无图片时不创建空 `images/`。
         不生成 marker 默认的 `_meta.json`。
 
         Args:

{sdpy_kit-0.4.3/kit → sdpy_kit-0.4.5/kit/docs}/md2doc_kit.py

@@ -22,7 +22,7 @@ Author: Clark Chang
 
 本模块基于 PiMD（pimd >= 2.2.5）将 Markdown 转换为 Word（.docx）与独立
 HTML；PDF 由本模块内嵌的 fpdf2 渲染器直接生成，保证中文与表格完整。
-各类文档（Office/PDF）→ Markdown 的正向解析见 kit.anydoc_kit（AnyDocKit）。
+各类文档（Office/PDF）→ Markdown 的正向解析见 kit.docs.anydoc_kit（AnyDocKit）。
 
 设计要点：
 - 全部使用静态方法提供服务，无内部状态；PiMD 转换引擎为模块级单例，按进程
@@ -1056,7 +1056,7 @@ class Md2DocKit:
     convert_md_to_pdf 方法说明）；需要 PDF 时优先用 convert_md_to_html
     后在浏览器中打印/另存 PDF，或 convert_md_to_docx 后在 Word 中另存 PDF。
 
-    各类文档（Office/PDF）→ Markdown 的正向解析见 kit.anydoc_kit（AnyDocKit）。
+    各类文档（Office/PDF）→ Markdown 的正向解析见 kit.docs.anydoc_kit（AnyDocKit）。
     可与 FileKit 组合使用以访问 FILE_STORAGE_ROOT 下的相对路径文件：
         full_path = FileKit.get_full_path("docs/report.md")
         Md2DocKit.convert_md_to_html(full_path)

{sdpy_kit-0.4.3 → sdpy_kit-0.4.5}/pyproject.toml

@@ -47,11 +47,11 @@ dynamic = ["version"]
 #   sqliteai → sqlite_kit 向量方法（numpy/sqliteai-vector，向量扩展）
 #   redis  → redis_kit
 #   ai     → kit/ai 服务池（httpx；dotenv 由 kit.ai 直接 import，故显式声明）
-#   md2doc → md2doc_kit（pimd/markdown-it-py，fpdf2；extra 名与模块名一致）
-#   anydoc → anydoc_kit（firecrawl-anydoc + pikepdf，显式声明）
-#   docx   → docx_kit（docxtpl + python-docx，模板动态填充）
-#   mineru → mineru_kit（requests）
-#   marker → marker_kit（marker-pdf[full]，本地模型解析 PDF→Markdown+Images）
+#   md2doc → kit.docs.md2doc_kit（pimd/markdown-it-py，fpdf2；extra 名沿用模块族名）
+#   anydoc → kit.docs.anydoc_kit（firecrawl-anydoc + pikepdf，显式声明）
+#   docx   → kit.docs.docx_kit（docxtpl + python-docx，模板动态填充）
+#   mineru → kit.docs.mineru_kit（requests）
+#   marker → kit.docs.marker_kit（marker-pdf[full]，本地模型解析 PDF→Markdown+Images）
 #   laya   → laya_kit（laya + torch，本地类型化决策引擎 choice/score/noul）
 #   web-article → crawl/web_article_kit（trafilatura，通用网页文章抓取转存）
 # 基础版 = config/log + kit.db 核心，SQLite 常规操作用标准库 sqlite3，零额外依赖。