sdpy-kit 0.1.13__tar.gz → 0.2.0__tar.gz

{sdpy_kit-0.1.13 → sdpy_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.1.13
+Version: 0.2.0
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -30,6 +30,7 @@ Requires-Dist: fastmcp>=4.0.5; extra == 'all'
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
 Requires-Dist: httpx>=0.28.1; extra == 'all'
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
+Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'all'
 Requires-Dist: numpy>=2.5.3; extra == 'all'
 Requires-Dist: pikepdf>=10.13.0; extra == 'all'
 Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'all'
@@ -45,6 +46,8 @@ Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
 Requires-Dist: pikepdf>=10.13.0; extra == 'anydoc'
 Provides-Extra: docx
 Requires-Dist: docxtpl>=0.20.2; extra == 'docx'
+Provides-Extra: marker
+Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'marker'
 Provides-Extra: mcp
 Requires-Dist: fastmcp>=4.0.5; extra == 'mcp'
 Provides-Extra: md2doc
@@ -72,7 +75,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
 - **MCP 客户端**：streamable-http / sse 双传输，档案驱动多服务器；
-- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / 向量库。
+- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（md + images） / 向量库 / 微信公众号文章抓取存储。
 
 > 要求 Python 3.13+
 
@@ -91,7 +94,9 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `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.zvec_kit` | `ZvecKit` | zvec 本地向量库 | `zvec` |
+| `kit.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
 
 ## 安装
 
@@ -116,6 +121,7 @@ uv add sdpy-kit
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
+| `marker` | MarkerKit 本地文档解析（marker-pdf[full] → Markdown + Images，依赖体积大） | `pip install "sdpy-kit[marker]"` |
 | `all` | 全部能力 | `pip install "sdpy-kit[all]"` |
 
 ## 配置（.env）
@@ -160,11 +166,17 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 # MinerU（仅精准解析需要 Key，Agent 轻量解析免登录）
 # MINERU_API_KEY=
+
+# Marker（本地解析，可选依赖 sdpy-kit[marker]）
+# MARKER_MODE=fast              # None=按设备自动（GPU→balanced / CPU、MPS→fast）
+# MARKER_HF_ENDPOINT=https://hf-mirror.com
+# MARKER_HF_DISABLE_XET=true
+# MARKER_LLAMA_CPP_BINARY=
 ```
 
 ### 环境变量 ↔ 能力对照表
 
-> 表中未出现的模块（`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`）不读取任何环境变量。
+> 表中未出现的模块（`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`、`kit.wx_article_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -224,7 +236,6 @@ SQLITE_DB_PATH=./data/sqlite.db
 | 环境变量 | 默认值 | 作用 |
 |----------|--------|------|
 | `AI_MODELS_CONFIG_PATH` | `./config/ai_models.json` | 档案文件位置；文件不存在时调用抛 `AIConfigError` |
-| *（已移除）* `AI_CHAT_PROFILES` 等 4 个 | — | 候选链顺序覆盖变量自 **0.1.13** 起移除：链顺序固定为「`default_profile` 打头 + JSON 声明顺序」；`.env` 中残留旧变量会被静默忽略（`Settings` 为 `extra="ignore"`） |
 | `KIT_AI_CHAIN_TIMEOUT` | 未设置 | 全局整链预算（秒）= 门面同步等待上限。⚠ **不是 `Settings` 字段**，由代码直读 `os.environ`，无类型/范围校验，非法值仅告警后回退 |
 | *（密钥，变量名由档案决定）* | 无 | 名字写在 `ai_models.json` 各档案的 `api_key` 字段（如 `SILICONFLOW_API_KEY`），值放 `.env` 或系统环境变量。未配置的档案会被剔除出候选链；该类型全部未配置则调用失败 |
 
@@ -247,6 +258,17 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `MINERU_POLL_INTERVAL` | `2.0`（≥0.5） | 任务轮询间隔 |
 | `MINERU_MAX_WAIT` | `600`（≥10） | 轮询总超时，超时抛 `MinerUError` |
 
+**Marker** → `kit.marker_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `MARKER_MODE` | 无（不写入 config） | 解析模式 `balanced` / `fast`；不配置则由 marker 按设备自动选择（GPU→balanced，CPU、MPS→fast） |
+| `MARKER_HF_ENDPOINT` | `https://hf-mirror.com` | 模型权重下载入口（国内镜像）；置空则用 HuggingFace 官方源 |
+| `MARKER_HF_DISABLE_XET` | `true` | 禁用 HF Xet 存储后端（国内镜像不支持，开启会导致权重下载挂起） |
+| `MARKER_LLAMA_CPP_BINARY` | 无 | `llama-server` 路径（非 NVIDIA 平台完整 VLM 能力）；未设置时沿用系统 `LLAMA_CPP_BINARY` |
+
+> 这四项由 kit 在**导入 marker 之前**经 `os.environ.setdefault` 应用：仅当用户未显式设置对应环境变量时生效，不覆盖显式配置。
+
 **云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -261,7 +283,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | ① Settings 变量 | 固定，kit 定义 | 上表中除 `KIT_AI_CHAIN_TIMEOUT` 与密钥类之外的全部 | pydantic-settings 读 `.env` 与真实环境变量（后者优先），带类型与范围校验，缺失用默认值 |
 | ② 直读变量 | 固定，kit 代码直接读 `os.environ` | `KIT_AI_CHAIN_TIMEOUT` | 无类型校验，非法值告警后回退 |
 | ③ 档案声明变量 | **动态**，名字写在 JSON 里 | AI 的 `api_key`、MCP 的 `token_env` | **名字进 JSON、值进 `.env`**——所以档案文件可以安全入库，密钥留在环境里 |
-| ④ 第三方库变量 | 由依赖库定义 | `FIRECRAWL_API_KEY`、`FIRECRAWL_API_URL` | kit 只透传 `None`，由 anydoc 自己回落读取 |
+| ④ 第三方库变量 | 由依赖库定义 | `FIRECRAWL_API_KEY`、`FIRECRAWL_API_URL`（anydoc）；`HF_ENDPOINT` / `HF_HUB_DISABLE_XET` / `LLAMA_CPP_BINARY`（marker） | anydoc：kit 只透传 `None`，由其自行回落；marker：kit 在导入前按 `MARKER_*` 配置做 `os.environ.setdefault`（不覆盖显式设置） |
 
 ### 密钥解析优先级
 
@@ -277,7 +299,8 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 | 改动内容 | 生效时机 |
 |----------|----------|
-| `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`ZVEC_*`、`MINERU_*` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
+| `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`ZVEC_*`、`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` 应用 → 改动需**重启进程**重新导入模块 |
 | AI 密钥写在 `.env` 里 | `.env` 只在加载档案时注入一次 → 重启，或 `AI.reload_config(reload_file=True)` |
 | AI 密钥由自己写入 `os.environ` | `AI.reload_config()`（默认 `reload_file=False`，只重读 `os.environ`） |
 | `ai_models.json`（增删档案、换 model） | `AI.reload_config(reload_file=True)` |
@@ -810,6 +833,46 @@ if r.state == "done":
 
 ---
 
+## kit.marker_kit —— 本地文档解析（Markdown + Images）
+
+安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf[full]`，含 torch 等 80+ 包，体积较大）
+
+```python
+from kit.marker_kit import MarkerKit
+
+# 落盘 md + images（推荐）：源文件同目录下建同名子目录
+md_path = MarkerKit.convert_to_dir("report.pdf")              # -> report/report.md + 图片
+md_path = MarkerKit.convert_to_dir("report.pdf", "out/doc")   # 指定产物目录
+
+# 只取 Markdown 文本（图片不落盘）
+md = MarkerKit.convert_to_md("report.pdf")
+
+# 安全转换（不抛异常，返回结果对象）
+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)
+
+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(src_path, output_dir=None, *, ...) -> MarkerResult` | 安全版：失败封装为 `MarkerResult`，不抛异常 |
+| `shutdown() -> None` | 释放模型与共享推理服务（幂等） |
+
+> 产物：`<output_dir>/<源文件名>.md` + 图片文件（md 内相对路径引用），**不生成** `_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` 跳过。
+
+---
+
 ## kit.zvec_kit —— 本地向量库
 
 安装：`pip install "sdpy-kit[zvec]"`
@@ -838,6 +901,48 @@ ZvecKit.flush("docs")
 
 ---
 
+## kit.wx_article_kit —— 微信公众号文章抓取存储
+
+零第三方依赖（标准库 `urllib` + 内置 HTML→Markdown 转换器），**无需 extra**，按需 import：
+
+```python
+from kit.wx_article_kit import WxArticleKit
+
+# 抓取解析（不落盘）
+result = WxArticleKit.fetch("https://mp.weixin.qq.com/s/xxxx")
+if result.ok:
+    print(result.info.title, result.info.author, result.info.publish_time)
+
+# 抓取并存储：<output_dir>/<file_name>/ 下 <file_name>.md + images/
+saved = WxArticleKit.save(url, output_dir="./output", file_name="12345")
+print(saved.md_path, saved.images_saved)
+
+# 需要结构化元信息时再产出 meta.json（默认不产出）
+WxArticleKit.save(url, "./output", "12345", write_meta=True)
+```
+
+| 方法 | 说明 |
+|------|------|
+| `fetch(url, timeout=20.0) -> ArticleResult` | 抓取并解析正文（不落盘）；结果对象字段 `ok` / `error` / `info`（`ArticleInfo`）/ `markdown` |
+| `save(url, output_dir, file_name, write_meta=False, timeout=20.0) -> SavedOutput` | 抓取并存储到 `<output_dir>/<file_name>/`；结果对象字段 `ok` / `error` / `output_dir` / `md_path` / `images_dir` / `title` / `images_saved` |
+
+落盘结构：
+
+```
+<output_dir>/<file_name>/
+├── <file_name>.md     # 正文 Markdown（YAML 头：title / author / publish_time / source_url）
+├── images/            # 图片转存（NNN.ext，正文引用已本地化）
+└── meta.json          # 可选：结构化元信息（write_meta=True 时产出）
+```
+
+- 元信息默认随 Markdown 的 YAML 头落盘（头部 `publish_time` 为中文日期，如 `2026年8月4日`）；
+  `ArticleInfo.publish_time` 与 `meta.json` 内仍为 ISO 8601（结构化数据）。
+- 无登录态抓取：命中微信风控（环境异常 / 访问过于频繁）时返回 `ok=False` + 原因，不破解验证码；
+  抓取或图片下载失败不抛异常，单张图片失败时正文保留原远程 URL。
+- 同名子目录**覆盖写**（不追加序号）；`file_name` 带 `.md` 后缀会自动去除，为空则抛 `ValueError`。
+
+---
+
 ## AI / MCP 档案文件
 
 AI 与 MCP 功能需要在项目根目录提供两个 JSON 档案文件：

{sdpy_kit-0.1.13 → sdpy_kit-0.2.0}/README.md

@@ -5,7 +5,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
 - **MCP 客户端**：streamable-http / sse 双传输，档案驱动多服务器；
-- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / 向量库。
+- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（md + images） / 向量库 / 微信公众号文章抓取存储。
 
 > 要求 Python 3.13+
 
@@ -24,7 +24,9 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `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.zvec_kit` | `ZvecKit` | zvec 本地向量库 | `zvec` |
+| `kit.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
 
 ## 安装
 
@@ -49,6 +51,7 @@ uv add sdpy-kit
 | `anydoc` | AnyDocKit 文档转 Markdown（firecrawl-anydoc + pikepdf） | `pip install "sdpy-kit[anydoc]"` |
 | `docx` | DocxKit 模板动态填充（docxtpl） | `pip install "sdpy-kit[docx]"` |
 | `mineru` | MinerUKit 解析 API（精准解析 + Agent 轻量解析） | `pip install "sdpy-kit[mineru]"` |
+| `marker` | MarkerKit 本地文档解析（marker-pdf[full] → Markdown + Images，依赖体积大） | `pip install "sdpy-kit[marker]"` |
 | `all` | 全部能力 | `pip install "sdpy-kit[all]"` |
 
 ## 配置（.env）
@@ -93,11 +96,17 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 # MinerU（仅精准解析需要 Key，Agent 轻量解析免登录）
 # MINERU_API_KEY=
+
+# Marker（本地解析，可选依赖 sdpy-kit[marker]）
+# MARKER_MODE=fast              # None=按设备自动（GPU→balanced / CPU、MPS→fast）
+# MARKER_HF_ENDPOINT=https://hf-mirror.com
+# MARKER_HF_DISABLE_XET=true
+# MARKER_LLAMA_CPP_BINARY=
 ```
 
 ### 环境变量 ↔ 能力对照表
 
-> 表中未出现的模块（`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`）不读取任何环境变量。
+> 表中未出现的模块（`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`、`kit.wx_article_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -157,7 +166,6 @@ SQLITE_DB_PATH=./data/sqlite.db
 | 环境变量 | 默认值 | 作用 |
 |----------|--------|------|
 | `AI_MODELS_CONFIG_PATH` | `./config/ai_models.json` | 档案文件位置；文件不存在时调用抛 `AIConfigError` |
-| *（已移除）* `AI_CHAT_PROFILES` 等 4 个 | — | 候选链顺序覆盖变量自 **0.1.13** 起移除：链顺序固定为「`default_profile` 打头 + JSON 声明顺序」；`.env` 中残留旧变量会被静默忽略（`Settings` 为 `extra="ignore"`） |
 | `KIT_AI_CHAIN_TIMEOUT` | 未设置 | 全局整链预算（秒）= 门面同步等待上限。⚠ **不是 `Settings` 字段**，由代码直读 `os.environ`，无类型/范围校验，非法值仅告警后回退 |
 | *（密钥，变量名由档案决定）* | 无 | 名字写在 `ai_models.json` 各档案的 `api_key` 字段（如 `SILICONFLOW_API_KEY`），值放 `.env` 或系统环境变量。未配置的档案会被剔除出候选链；该类型全部未配置则调用失败 |
 
@@ -180,6 +188,17 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `MINERU_POLL_INTERVAL` | `2.0`（≥0.5） | 任务轮询间隔 |
 | `MINERU_MAX_WAIT` | `600`（≥10） | 轮询总超时，超时抛 `MinerUError` |
 
+**Marker** → `kit.marker_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `MARKER_MODE` | 无（不写入 config） | 解析模式 `balanced` / `fast`；不配置则由 marker 按设备自动选择（GPU→balanced，CPU、MPS→fast） |
+| `MARKER_HF_ENDPOINT` | `https://hf-mirror.com` | 模型权重下载入口（国内镜像）；置空则用 HuggingFace 官方源 |
+| `MARKER_HF_DISABLE_XET` | `true` | 禁用 HF Xet 存储后端（国内镜像不支持，开启会导致权重下载挂起） |
+| `MARKER_LLAMA_CPP_BINARY` | 无 | `llama-server` 路径（非 NVIDIA 平台完整 VLM 能力）；未设置时沿用系统 `LLAMA_CPP_BINARY` |
+
+> 这四项由 kit 在**导入 marker 之前**经 `os.environ.setdefault` 应用：仅当用户未显式设置对应环境变量时生效，不覆盖显式配置。
+
 **云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -194,7 +213,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 | ① Settings 变量 | 固定，kit 定义 | 上表中除 `KIT_AI_CHAIN_TIMEOUT` 与密钥类之外的全部 | pydantic-settings 读 `.env` 与真实环境变量（后者优先），带类型与范围校验，缺失用默认值 |
 | ② 直读变量 | 固定，kit 代码直接读 `os.environ` | `KIT_AI_CHAIN_TIMEOUT` | 无类型校验，非法值告警后回退 |
 | ③ 档案声明变量 | **动态**，名字写在 JSON 里 | AI 的 `api_key`、MCP 的 `token_env` | **名字进 JSON、值进 `.env`**——所以档案文件可以安全入库，密钥留在环境里 |
-| ④ 第三方库变量 | 由依赖库定义 | `FIRECRAWL_API_KEY`、`FIRECRAWL_API_URL` | kit 只透传 `None`，由 anydoc 自己回落读取 |
+| ④ 第三方库变量 | 由依赖库定义 | `FIRECRAWL_API_KEY`、`FIRECRAWL_API_URL`（anydoc）；`HF_ENDPOINT` / `HF_HUB_DISABLE_XET` / `LLAMA_CPP_BINARY`（marker） | anydoc：kit 只透传 `None`，由其自行回落；marker：kit 在导入前按 `MARKER_*` 配置做 `os.environ.setdefault`（不覆盖显式设置） |
 
 ### 密钥解析优先级
 
@@ -210,7 +229,8 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 | 改动内容 | 生效时机 |
 |----------|----------|
-| `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`ZVEC_*`、`MINERU_*` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
+| `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`ZVEC_*`、`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` 应用 → 改动需**重启进程**重新导入模块 |
 | AI 密钥写在 `.env` 里 | `.env` 只在加载档案时注入一次 → 重启，或 `AI.reload_config(reload_file=True)` |
 | AI 密钥由自己写入 `os.environ` | `AI.reload_config()`（默认 `reload_file=False`，只重读 `os.environ`） |
 | `ai_models.json`（增删档案、换 model） | `AI.reload_config(reload_file=True)` |
@@ -743,6 +763,46 @@ if r.state == "done":
 
 ---
 
+## kit.marker_kit —— 本地文档解析（Markdown + Images）
+
+安装：`pip install "sdpy-kit[marker]"`（依赖 `marker-pdf[full]`，含 torch 等 80+ 包，体积较大）
+
+```python
+from kit.marker_kit import MarkerKit
+
+# 落盘 md + images（推荐）：源文件同目录下建同名子目录
+md_path = MarkerKit.convert_to_dir("report.pdf")              # -> report/report.md + 图片
+md_path = MarkerKit.convert_to_dir("report.pdf", "out/doc")   # 指定产物目录
+
+# 只取 Markdown 文本（图片不落盘）
+md = MarkerKit.convert_to_md("report.pdf")
+
+# 安全转换（不抛异常，返回结果对象）
+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)
+
+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(src_path, output_dir=None, *, ...) -> MarkerResult` | 安全版：失败封装为 `MarkerResult`，不抛异常 |
+| `shutdown() -> None` | 释放模型与共享推理服务（幂等） |
+
+> 产物：`<output_dir>/<源文件名>.md` + 图片文件（md 内相对路径引用），**不生成** `_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` 跳过。
+
+---
+
 ## kit.zvec_kit —— 本地向量库
 
 安装：`pip install "sdpy-kit[zvec]"`
@@ -771,6 +831,48 @@ ZvecKit.flush("docs")
 
 ---
 
+## kit.wx_article_kit —— 微信公众号文章抓取存储
+
+零第三方依赖（标准库 `urllib` + 内置 HTML→Markdown 转换器），**无需 extra**，按需 import：
+
+```python
+from kit.wx_article_kit import WxArticleKit
+
+# 抓取解析（不落盘）
+result = WxArticleKit.fetch("https://mp.weixin.qq.com/s/xxxx")
+if result.ok:
+    print(result.info.title, result.info.author, result.info.publish_time)
+
+# 抓取并存储：<output_dir>/<file_name>/ 下 <file_name>.md + images/
+saved = WxArticleKit.save(url, output_dir="./output", file_name="12345")
+print(saved.md_path, saved.images_saved)
+
+# 需要结构化元信息时再产出 meta.json（默认不产出）
+WxArticleKit.save(url, "./output", "12345", write_meta=True)
+```
+
+| 方法 | 说明 |
+|------|------|
+| `fetch(url, timeout=20.0) -> ArticleResult` | 抓取并解析正文（不落盘）；结果对象字段 `ok` / `error` / `info`（`ArticleInfo`）/ `markdown` |
+| `save(url, output_dir, file_name, write_meta=False, timeout=20.0) -> SavedOutput` | 抓取并存储到 `<output_dir>/<file_name>/`；结果对象字段 `ok` / `error` / `output_dir` / `md_path` / `images_dir` / `title` / `images_saved` |
+
+落盘结构：
+
+```
+<output_dir>/<file_name>/
+├── <file_name>.md     # 正文 Markdown（YAML 头：title / author / publish_time / source_url）
+├── images/            # 图片转存（NNN.ext，正文引用已本地化）
+└── meta.json          # 可选：结构化元信息（write_meta=True 时产出）
+```
+
+- 元信息默认随 Markdown 的 YAML 头落盘（头部 `publish_time` 为中文日期，如 `2026年8月4日`）；
+  `ArticleInfo.publish_time` 与 `meta.json` 内仍为 ISO 8601（结构化数据）。
+- 无登录态抓取：命中微信风控（环境异常 / 访问过于频繁）时返回 `ok=False` + 原因，不破解验证码；
+  抓取或图片下载失败不抛异常，单张图片失败时正文保留原远程 URL。
+- 同名子目录**覆盖写**（不追加序号）；`file_name` 带 `.md` 后缀会自动去除，为空则抛 `ValueError`。
+
+---
+
 ## AI / MCP 档案文件
 
 AI 与 MCP 功能需要在项目根目录提供两个 JSON 档案文件：

{sdpy_kit-0.1.13 → sdpy_kit-0.2.0}/kit/__init__.py

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

{sdpy_kit-0.1.13 → sdpy_kit-0.2.0}/kit/config/kit_config.py

@@ -121,6 +121,27 @@ class Settings(BaseSettings):
         default=600, ge=10, description="任务轮询总超时（秒），超时抛 MinerUError"
     )
 
+    # Marker 本地文档解析配置（marker-pdf，PDF→Markdown+Images，模型本地运行）
+    MARKER_MODE: str | None = Field(
+        default=None,
+        description=(
+            "解析模式：None=按设备自动（GPU→balanced，CPU/MPS→fast），"
+            "可设 balanced/fast"
+        ),
+    )
+    MARKER_HF_ENDPOINT: str = Field(
+        default="https://hf-mirror.com",
+        description="模型权重下载入口（默认国内镜像），置空则使用 HuggingFace 官方源",
+    )
+    MARKER_HF_DISABLE_XET: bool = Field(
+        default=True,
+        description="禁用 HF Xet 存储后端（国内镜像不支持，开启会导致权重下载挂起）",
+    )
+    MARKER_LLAMA_CPP_BINARY: str | None = Field(
+        default=None,
+        description="llama-server 可执行文件路径（None 时沿用系统 LLAMA_CPP_BINARY）",
+    )
+
     class Config:
         env_file = ".env"
         env_file_encoding = "utf-8"