sdpy-kit 0.3.0__tar.gz → 0.3.1__tar.gz

{sdpy_kit-0.3.0 → sdpy_kit-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.3.0
+Version: 0.3.1
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -42,6 +42,7 @@ Requires-Dist: python-dotenv>=1.2.4; 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'
+Requires-Dist: trafilatura>=2.3.1; extra == 'all'
 Requires-Dist: zvec>=0.7.0; extra == 'all'
 Provides-Extra: anydoc
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
@@ -69,6 +70,8 @@ Requires-Dist: redis>=8.1.0; extra == 'redis'
 Provides-Extra: sqliteai
 Requires-Dist: numpy>=2.5.4; extra == 'sqliteai'
 Requires-Dist: sqliteai-vector>=1.1.2; extra == 'sqliteai'
+Provides-Extra: web-article
+Requires-Dist: trafilatura>=2.3.1; extra == 'web-article'
 Provides-Extra: zvec
 Requires-Dist: zvec>=0.7.0; extra == 'zvec'
 Description-Content-Type: text/markdown
@@ -80,7 +83,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 - **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；
 - **AI 多模型服务池**：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
 - **MCP 客户端**：streamable-http / sse 双传输，档案驱动多服务器；
-- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（md + images） / 向量库 / 微信公众号文章抓取存储。
+- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（md + images） / Laya 类型化决策 / 向量库 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
 
 > 要求 Python 3.13+
 
@@ -100,8 +103,11 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `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.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
 | `kit.zvec_kit` | `ZvecKit` | zvec 本地向量库 | `zvec` |
+| `kit.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（两 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
 | `kit.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
+| `kit.web_article_kit` | `WebArticleKit` | 通用网页文章 → Markdown + 图片转存（**不含微信**，微信请用 `WxArticleKit`；明确支持头条） | `web-article` |
 
 ## 安装
 
@@ -127,6 +133,8 @@ uv add sdpy-kit
 | `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]"` |
+| `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]"` |
 
 ## 配置（.env）
@@ -177,11 +185,17 @@ SQLITE_DB_PATH=./data/sqlite.db
 # MARKER_HF_ENDPOINT=https://hf-mirror.com
 # MARKER_HF_DISABLE_XET=true
 # MARKER_LLAMA_CPP_BINARY=
+
+# Laya（类型化决策，可选依赖 sdpy-kit[laya]）
+# LAYA_MODEL=multilingual       # multilingual / english / typed-decisions
+# LAYA_DEVICE=                  # 留空由 laya 自动选择
+# LAYA_HF_ENDPOINT=https://hf-mirror.com
+# LAYA_HF_DISABLE_XET=true
 ```
 
 ### 环境变量 ↔ 能力对照表
 
-> 表中未出现的模块（`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`、`kit.wx_article_kit`）不读取任何环境变量。
+> 表中未出现的模块（`kit.article_models`、`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`、`kit.wx_article_kit`、`kit.web_article_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -274,6 +288,18 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 > 这四项由 kit 在**导入 marker 之前**经 `os.environ.setdefault` 应用：仅当用户未显式设置对应环境变量时生效，不覆盖显式配置。
 
+**Laya** → `kit.laya_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `LAYA_MODEL` | `multilingual` | 检查点：`multilingual`（多语言含中文）/ `english` / `typed-decisions` |
+| `LAYA_DEVICE` | 无（不写入 config） | 推理设备（`cpu` / `cuda`）；不配置则由 laya 自动选择 |
+| `LAYA_HF_ENDPOINT` | `https://hf-mirror.com` | 检查点权重下载入口（国内镜像）；置空则用 HuggingFace 官方源 |
+| `LAYA_HF_DISABLE_XET` | `true` | 禁用 HF Xet 存储后端（国内镜像不支持，开启会导致权重下载挂起） |
+
+> `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
+> `LAYA_MODEL` / `LAYA_DEVICE` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
+
 **云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -306,6 +332,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 |----------|----------|
 | `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` 应用 → 改动需**重启进程**重新导入模块 |
+| `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`） |
 | `ai_models.json`（增删档案、换 model） | `AI.reload_config(reload_file=True)` |
@@ -1118,7 +1145,7 @@ WxArticleKit.save(url, "./output", "12345", write_meta=True)
 
 ```
 <output_dir>/<file_name>/
-├── <file_name>.md     # 正文 Markdown（YAML 头：title / author / publish_time / source_url）
+├── <file_name>.md     # 正文 Markdown（YAML 头：title / author / publish_time / source / source_url）
 ├── images/            # 图片转存（NNN.ext，正文引用已本地化）
 └── meta.json          # 可选：结构化元信息（write_meta=True 时产出）
 ```
@@ -1127,10 +1154,65 @@ WxArticleKit.save(url, "./output", "12345", write_meta=True)
   `ArticleInfo.publish_time` 与 `meta.json` 内仍为 ISO 8601（结构化数据）。
 - 无登录态抓取：命中微信风控（环境异常 / 访问过于频繁）时返回 `ok=False` + 原因，不破解验证码；
   抓取或图片下载失败不抛异常，单张图片失败时正文保留原远程 URL。
+- 模型与 `WebArticleKit` 共用 `kit.article_models`（`ArticleInfo` 含 `source` / `site_host`）；
+  失败时 `reason` 为类型化分类（微信常用 `risk_control` / `no_content` / `fetch_failed`）。
 - 同名子目录**覆盖写**（不追加序号）；`file_name` 带 `.md` 后缀会自动去除，为空则抛 `ValueError`。
 
 ---
 
+## kit.web_article_kit —— 通用网页文章抓取存储
+
+可选依赖（`trafilatura`），需安装 `pip install "sdpy-kit[web-article]"`，按需 import：
+
+```python
+from kit.web_article_kit import WebArticleKit
+
+# 抓取解析（不落盘）
+result = WebArticleKit.fetch("https://blog.csdn.net/xxx/article/details/123")
+if result.ok:
+    print(result.info.source, result.info.title, result.info.publish_time)
+
+# 抓取并存储：<output_dir>/<file_name>/ 下 <file_name>.md + images/
+saved = WebArticleKit.save(url, output_dir="./output", file_name="12345")
+print(saved.md_path, saved.images_saved)
+
+# 需要结构化元信息时再产出 meta.json（默认不产出）
+WebArticleKit.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>/`；字段与 `WxArticleKit.save` 一致 |
+
+落盘结构与 `WxArticleKit` 完全一致（`<file_name>.md` + `images/`，`write_meta=True` 时多出 `meta.json`）；
+`<file_name>.md` 的 YAML 头为 `title / author / publish_time / source / source_url`（`publish_time` 渲染为中文日期）。
+
+**站点覆盖范围**（规则表只允许「转交」与「接口适配」两类条目，不做逐站 DOM 补丁）：
+
+| 站点类型 | 行为 |
+|---|---|
+| 通用静态 / 服务端渲染页面（博客、文档站、CSDN 等） | ✅ 直接抽取 |
+| 头条（文章页为 JS 空壳） | ✅ **明确支持**：走移动端 JSON 接口 |
+| 微信公众号 | ❌ **不覆盖**：返回提示，请改用 `kit.wx_article_kit.WxArticleKit`（该来源有专属解析，二者各自独立） |
+| 正文依赖 JavaScript 动态渲染或需登录态的站点 | ❌ 失败并给出**类型化说明**（不维护域名名单） |
+
+`ArticleInfo` 为平台中立的通用字段集：`url` / `title` / `author` / `publish_time`（ISO 8601）/ `source`
+（来源平台名）/ `site_host` / `summary` / `images` / `links` / `code_blocks`，便于多平台抓取后写入同一张表；
+`to_dict()` 可直接 JSON 化（即 `meta.json` 的内容）。模型定义在 `kit.article_models`，与
+`WxArticleKit` **共用同一套**。
+
+质量信号（均不改变成功语义）：
+
+| 字段 | 取值 / 含义 |
+|---|---|
+| `reason` | 失败时的类型化分类：`unsupported_source` / `fetch_blocked` / `fetch_failed` / `no_content` / `risk_control`（成功为空串） |
+| `warnings` | **非致命**抽取自检提示（`tuple[str, ...]`）：正文疑似过短、页面含图片但产物无图；同时写入 warning 日志 |
+
+标题统一去除站点后缀（如 CSDN 的 `标题-CSDN博客`）；刻意不做「与页面 h1 择优」（h1 可能是导航文案）。
+
+---
+
 ## AI / MCP 档案文件
 
 AI 与 MCP 功能需要在项目根目录提供两个 JSON 档案文件：

{sdpy_kit-0.3.0 → sdpy_kit-0.3.1}/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 解析 / Marker 本地解析（md + images） / 向量库 / 微信公众号文章抓取存储。
+- **工具集**：Redis / 文件 / 雪花 ID / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（md + images） / Laya 类型化决策 / 向量库 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
 
 > 要求 Python 3.13+
 
@@ -25,8 +25,11 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `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.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
 | `kit.zvec_kit` | `ZvecKit` | zvec 本地向量库 | `zvec` |
+| `kit.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（两 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
 | `kit.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
+| `kit.web_article_kit` | `WebArticleKit` | 通用网页文章 → Markdown + 图片转存（**不含微信**，微信请用 `WxArticleKit`；明确支持头条） | `web-article` |
 
 ## 安装
 
@@ -52,6 +55,8 @@ uv add sdpy-kit
 | `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]"` |
+| `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]"` |
 
 ## 配置（.env）
@@ -102,11 +107,17 @@ SQLITE_DB_PATH=./data/sqlite.db
 # MARKER_HF_ENDPOINT=https://hf-mirror.com
 # MARKER_HF_DISABLE_XET=true
 # MARKER_LLAMA_CPP_BINARY=
+
+# Laya（类型化决策，可选依赖 sdpy-kit[laya]）
+# LAYA_MODEL=multilingual       # multilingual / english / typed-decisions
+# LAYA_DEVICE=                  # 留空由 laya 自动选择
+# LAYA_HF_ENDPOINT=https://hf-mirror.com
+# LAYA_HF_DISABLE_XET=true
 ```
 
 ### 环境变量 ↔ 能力对照表
 
-> 表中未出现的模块（`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`、`kit.wx_article_kit`）不读取任何环境变量。
+> 表中未出现的模块（`kit.article_models`、`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`、`kit.wx_article_kit`、`kit.web_article_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -199,6 +210,18 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 > 这四项由 kit 在**导入 marker 之前**经 `os.environ.setdefault` 应用：仅当用户未显式设置对应环境变量时生效，不覆盖显式配置。
 
+**Laya** → `kit.laya_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `LAYA_MODEL` | `multilingual` | 检查点：`multilingual`（多语言含中文）/ `english` / `typed-decisions` |
+| `LAYA_DEVICE` | 无（不写入 config） | 推理设备（`cpu` / `cuda`）；不配置则由 laya 自动选择 |
+| `LAYA_HF_ENDPOINT` | `https://hf-mirror.com` | 检查点权重下载入口（国内镜像）；置空则用 HuggingFace 官方源 |
+| `LAYA_HF_DISABLE_XET` | `true` | 禁用 HF Xet 存储后端（国内镜像不支持，开启会导致权重下载挂起） |
+
+> `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
+> `LAYA_MODEL` / `LAYA_DEVICE` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
+
 **云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -231,6 +254,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 |----------|----------|
 | `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` 应用 → 改动需**重启进程**重新导入模块 |
+| `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`） |
 | `ai_models.json`（增删档案、换 model） | `AI.reload_config(reload_file=True)` |
@@ -1043,7 +1067,7 @@ WxArticleKit.save(url, "./output", "12345", write_meta=True)
 
 ```
 <output_dir>/<file_name>/
-├── <file_name>.md     # 正文 Markdown（YAML 头：title / author / publish_time / source_url）
+├── <file_name>.md     # 正文 Markdown（YAML 头：title / author / publish_time / source / source_url）
 ├── images/            # 图片转存（NNN.ext，正文引用已本地化）
 └── meta.json          # 可选：结构化元信息（write_meta=True 时产出）
 ```
@@ -1052,10 +1076,65 @@ WxArticleKit.save(url, "./output", "12345", write_meta=True)
   `ArticleInfo.publish_time` 与 `meta.json` 内仍为 ISO 8601（结构化数据）。
 - 无登录态抓取：命中微信风控（环境异常 / 访问过于频繁）时返回 `ok=False` + 原因，不破解验证码；
   抓取或图片下载失败不抛异常，单张图片失败时正文保留原远程 URL。
+- 模型与 `WebArticleKit` 共用 `kit.article_models`（`ArticleInfo` 含 `source` / `site_host`）；
+  失败时 `reason` 为类型化分类（微信常用 `risk_control` / `no_content` / `fetch_failed`）。
 - 同名子目录**覆盖写**（不追加序号）；`file_name` 带 `.md` 后缀会自动去除，为空则抛 `ValueError`。
 
 ---
 
+## kit.web_article_kit —— 通用网页文章抓取存储
+
+可选依赖（`trafilatura`），需安装 `pip install "sdpy-kit[web-article]"`，按需 import：
+
+```python
+from kit.web_article_kit import WebArticleKit
+
+# 抓取解析（不落盘）
+result = WebArticleKit.fetch("https://blog.csdn.net/xxx/article/details/123")
+if result.ok:
+    print(result.info.source, result.info.title, result.info.publish_time)
+
+# 抓取并存储：<output_dir>/<file_name>/ 下 <file_name>.md + images/
+saved = WebArticleKit.save(url, output_dir="./output", file_name="12345")
+print(saved.md_path, saved.images_saved)
+
+# 需要结构化元信息时再产出 meta.json（默认不产出）
+WebArticleKit.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>/`；字段与 `WxArticleKit.save` 一致 |
+
+落盘结构与 `WxArticleKit` 完全一致（`<file_name>.md` + `images/`，`write_meta=True` 时多出 `meta.json`）；
+`<file_name>.md` 的 YAML 头为 `title / author / publish_time / source / source_url`（`publish_time` 渲染为中文日期）。
+
+**站点覆盖范围**（规则表只允许「转交」与「接口适配」两类条目，不做逐站 DOM 补丁）：
+
+| 站点类型 | 行为 |
+|---|---|
+| 通用静态 / 服务端渲染页面（博客、文档站、CSDN 等） | ✅ 直接抽取 |
+| 头条（文章页为 JS 空壳） | ✅ **明确支持**：走移动端 JSON 接口 |
+| 微信公众号 | ❌ **不覆盖**：返回提示，请改用 `kit.wx_article_kit.WxArticleKit`（该来源有专属解析，二者各自独立） |
+| 正文依赖 JavaScript 动态渲染或需登录态的站点 | ❌ 失败并给出**类型化说明**（不维护域名名单） |
+
+`ArticleInfo` 为平台中立的通用字段集：`url` / `title` / `author` / `publish_time`（ISO 8601）/ `source`
+（来源平台名）/ `site_host` / `summary` / `images` / `links` / `code_blocks`，便于多平台抓取后写入同一张表；
+`to_dict()` 可直接 JSON 化（即 `meta.json` 的内容）。模型定义在 `kit.article_models`，与
+`WxArticleKit` **共用同一套**。
+
+质量信号（均不改变成功语义）：
+
+| 字段 | 取值 / 含义 |
+|---|---|
+| `reason` | 失败时的类型化分类：`unsupported_source` / `fetch_blocked` / `fetch_failed` / `no_content` / `risk_control`（成功为空串） |
+| `warnings` | **非致命**抽取自检提示（`tuple[str, ...]`）：正文疑似过短、页面含图片但产物无图；同时写入 warning 日志 |
+
+标题统一去除站点后缀（如 CSDN 的 `标题-CSDN博客`）；刻意不做「与页面 h1 择优」（h1 可能是导航文案）。
+
+---
+
 ## AI / MCP 档案文件
 
 AI 与 MCP 功能需要在项目根目录提供两个 JSON 档案文件：

{sdpy_kit-0.3.0 → sdpy_kit-0.3.1}/kit/__init__.py

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

sdpy_kit-0.3.1/kit/article_models.py

@@ -0,0 +1,162 @@
+"""
+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-14
+"""文章抓取通用模型（多平台共用，零第三方依赖）
+
+`kit.wx_article_kit.WxArticleKit`（微信公众号）与 `kit.web_article_kit.WebArticleKit`
+（通用网页）共用同一套模型，便于**多平台抓取后写入同一张表**：
+
+- `ArticleImage` / `ArticleLink` / `CodeBlock`：正文清单条目；
+- `ArticleInfo`：平台中立的通用字段集（`publish_time` 保持 ISO 8601，
+  仅落盘 YAML 头渲染为中文日期）；
+- `ArticleResult`：`fetch()` 的非落盘结果；
+- `SavedOutput`：`save()` 的落盘结果。
+
+失败原因（`ArticleResult.reason` / `SavedOutput.reason`）取值：
+
+| 取值 | 含义 |
+|---|---|
+| `""` | 成功 |
+| `unsupported_source` | 该来源有专属工具类（如微信 → `WxArticleKit`） |
+| `fetch_blocked` | 抓取被站点拒绝（403 等）：正文通常依赖 JavaScript 渲染或需登录态 |
+| `fetch_failed` | 网络/超时等抓取失败 |
+| `no_content` | 抓到页面但无法识别正文（非文章页或正文由 JavaScript 动态渲染） |
+| `risk_control` | 命中站点风控特征（访问过于频繁/环境异常） |
+
+`warnings` 为**非致命**自检提示（如「页面含图片但产物无图」「正文疑似过短」），
+**不改变 `ok` 语义**：抓取成功一律 `ok=True`，提示仅供调用方判断质量。
+
+使用方式（按需 import，无需经 kit 包顶层导出）：
+
+    from kit.article_models import ArticleInfo, ArticleResult
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, NamedTuple
+
+# 失败原因取值（字符串常量，便于业务侧分支判断；成功为空串）
+REASON_UNSUPPORTED_SOURCE = "unsupported_source"
+REASON_FETCH_BLOCKED = "fetch_blocked"
+REASON_FETCH_FAILED = "fetch_failed"
+REASON_NO_CONTENT = "no_content"
+REASON_RISK_CONTROL = "risk_control"
+
+# 全部合法取值（便于校验收敛）
+REASONS: tuple[str, ...] = (
+    "",
+    REASON_UNSUPPORTED_SOURCE,
+    REASON_FETCH_BLOCKED,
+    REASON_FETCH_FAILED,
+    REASON_NO_CONTENT,
+    REASON_RISK_CONTROL,
+)
+
+
+class ArticleImage(NamedTuple):
+    """图片条目（转存后地址 + 原始地址 + alt + 本地相对路径）"""
+
+    src: str
+    original: str
+    alt: str = ""
+    local: str = ""  # 转存后的本地相对路径（如 images/001.png），失败为空
+
+
+class ArticleLink(NamedTuple):
+    """正文链接条目"""
+
+    text: str
+    href: str
+
+
+class CodeBlock(NamedTuple):
+    """代码块条目"""
+
+    language: str
+    code: str
+
+
+@dataclass
+class ArticleInfo:
+    """文章元信息（平台中立的通用字段集，`to_dict()` 可 JSON 化后自行持久化）
+
+    字段说明：
+
+    - `url`：原文链接；
+    - `title` / `author` / `summary`：标题 / 作者 / 摘要，取不到时为空串；
+    - `publish_time`：ISO 8601（精度不足时退化为 `YYYY-MM-DD`），
+      落盘 YAML 头渲染中文日期；
+    - `source`：来源平台名（如「今日头条」「CSDN博客」「微信公众平台」）；
+    - `site_host`：站点域名（DB 归类/去重辅助）；
+    - `images` / `links` / `code_blocks`：正文清单（图片 `local` 在落盘阶段填充）。
+    """
+
+    url: str
+    title: str
+    author: str = ""
+    publish_time: str = ""
+    source: str = ""
+    site_host: str = ""
+    summary: str = ""
+    images: list[ArticleImage] = field(default_factory=list)
+    links: list[ArticleLink] = field(default_factory=list)
+    code_blocks: list[CodeBlock] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """序列化为可 JSON 化的 dict"""
+        return {
+            "url": self.url,
+            "title": self.title,
+            "author": self.author,
+            "publish_time": self.publish_time,
+            "source": self.source,
+            "site_host": self.site_host,
+            "summary": self.summary,
+            "images": [img._asdict() for img in self.images],
+            "links": [link._asdict() for link in self.links],
+            "code_blocks": [code._asdict() for code in self.code_blocks],
+        }
+
+
+class ArticleResult(NamedTuple):
+    """fetch() 的非落盘结果
+
+    `reason` 见模块 docstring；`warnings` 为非致命自检提示（不可变元组）。
+    """
+
+    ok: bool
+    error: str = ""
+    info: ArticleInfo | None = None
+    markdown: str = ""
+    reason: str = ""
+    warnings: tuple[str, ...] = ()
+
+
+class SavedOutput(NamedTuple):
+    """save() 的落盘结果"""
+
+    ok: bool
+    error: str = ""
+    output_dir: str = ""  # 实际写入的文章子目录（<output_dir>/<file_name>）
+    md_path: str = ""
+    images_dir: str = ""
+    title: str = ""
+    images_saved: int = 0  # 成功转存的图片张数
+    reason: str = ""
+    warnings: tuple[str, ...] = ()