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

{sdpy_kit-0.3.0 → sdpy_kit-0.4.0}/.gitignore

@@ -55,12 +55,10 @@ target/
 Thumbs.db
 Servers
 .metadata
-# 根目录 data/ 运行时数据（zvec 向量库、SQLite 测试库等，不入库）
+# 根目录 data/ 运行时数据（SQLite 测试库等，不入库）
 data/
 # AI 文生图 e2e 测试产物（生成的海报图片，不入库）
 tests/image/
-# AMiner 检索测试产物（md 报告，不入库）
-tests/aminer/
 # SQLite 测试库（运行时生成，不入库）
 metadata_log.db
 upload

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.3.0
-Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
+Version: 0.4.0
+Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
-Keywords: ai,kit,mcp,mysql,postgresql,redis,sdpy,sqlalchemy,sqlite,sqlmodel,向量检索,工具集,开发工具,数据库
+Keywords: ai,kit,mysql,postgresql,redis,sdpy,sqlalchemy,sqlite,sqlmodel,向量检索,工具集,开发工具,数据库
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -26,7 +26,6 @@ Requires-Dist: httpx>=0.28.1; extra == 'ai'
 Requires-Dist: python-dotenv>=1.2.4; extra == 'ai'
 Provides-Extra: all
 Requires-Dist: docxtpl>=0.20.2; extra == 'all'
-Requires-Dist: fastmcp>=4.1.0; extra == 'all'
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
 Requires-Dist: httpx>=0.28.1; extra == 'all'
 Requires-Dist: huggingface-hub<2,>=1.5; extra == 'all'
@@ -42,7 +41,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: zvec>=0.7.0; extra == 'all'
+Requires-Dist: trafilatura>=2.3.1; extra == 'all'
 Provides-Extra: anydoc
 Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
 Requires-Dist: pikepdf>=10.17.0; extra == 'anydoc'
@@ -53,8 +52,6 @@ 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'
-Provides-Extra: mcp
-Requires-Dist: fastmcp>=4.1.0; extra == 'mcp'
 Provides-Extra: md2doc
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'md2doc'
 Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'md2doc'
@@ -69,8 +66,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: zvec
-Requires-Dist: zvec>=0.7.0; extra == 'zvec'
+Provides-Extra: web-article
+Requires-Dist: trafilatura>=2.3.1; extra == 'web-article'
 Description-Content-Type: text/markdown
 
 # sdpy-kit
@@ -79,8 +76,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+
 
@@ -91,7 +87,6 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.config` | `get_settings` / `get_default_logger` | 配置单例与统一日志 | 无 |
 | `kit.db` | `SQLiteKit` / `PgKit` / `MySqlKit` / `CRUDBase` | 统一 CRUD、原生 SQL、原生表操作、事务、表管理 | `pg` / `mysql` / `sqliteai` |
 | `kit.ai` | `AI`（同步门面）/ 4 个原生异步 Service | 对话 / 向量化 / 重排序 / 文生图 | `ai` |
-| `kit.mcp_kit` | `McpKit` | MCP 工具发现与调用 | `mcp` |
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
 | `kit.file_kit` | `FileKit` | 文件与目录读写、移动、遍历 | 无 |
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
@@ -100,8 +95,10 @@ 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.zvec_kit` | `ZvecKit` | zvec 本地向量库 | `zvec` |
-| `kit.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
+| `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 + 图片转存 | 无 |
+| `kit.crawl.web_article_kit` | `WebArticleKit` | 通用网页文章 → Markdown + 图片转存（**不含微信**，微信请用 `WxArticleKit`；明确支持头条） | `web-article` |
 
 ## 安装
 
@@ -118,15 +115,15 @@ uv add sdpy-kit
 | `pg` | PgKit（PostgreSQL 驱动；向量方法另需服务端 pgvector） | `pip install "sdpy-kit[pg]"` |
 | `mysql` | MySqlKit（MySQL 驱动；向量仅存储，需 MySQL 9.x） | `pip install "sdpy-kit[mysql]"` |
 | `sqliteai` | SQLiteKit 向量方法（numpy / sqliteai-vector，SQLite 向量扩展） | `pip install "sdpy-kit[sqliteai]"` |
-| `zvec` | ZvecKit（zvec，阿里独立向量库） | `pip install "sdpy-kit[zvec]"` |
 | `redis` | RedisKit | `pip install "sdpy-kit[redis]"` |
-| `mcp` | McpKit（fastmcp） | `pip install "sdpy-kit[mcp]"` |
 | `ai` | AI 服务池（httpx + python-dotenv） | `pip install "sdpy-kit[ai]"` |
 | `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]"` |
 | `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）
@@ -159,16 +156,11 @@ SQLITE_DB_PATH=./data/sqlite.db
 # REDIS_DB=0
 # REDIS_PASSWORD=
 # FILE_STORAGE_ROOT=./data
-# ZVEC_DATA_DIR=./data/zvec
 
 # AI：档案路径 + 你为各模型档案自定的密钥变量名（变量名在 ai_models.json 里声明）
 # AI_MODELS_CONFIG_PATH=./config/ai_models.json
 # SILICONFLOW_API_KEY=sk-xxxxxx
 
-# MCP：档案路径 + 你为各服务器自定的 token 变量名（变量名在 mcp_servers.json 里声明）
-# MCP_SERVERS_CONFIG_PATH=./config/mcp_servers.json
-# AMINER_TOKEN=xxxxxx
-
 # MinerU（仅精准解析需要 Key，Agent 轻量解析免登录）
 # MINERU_API_KEY=
 
@@ -177,11 +169,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.crawl.article_models`、`kit.common_kit`、`kit.docx_kit`、`kit.md2doc_kit`、`kit.crawl.wx_article_kit`、`kit.crawl.web_article_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -224,18 +222,6 @@ SQLITE_DB_PATH=./data/sqlite.db
 |----------|--------|------|
 | `FILE_STORAGE_ROOT` | `./data` | FileKit 全部相对路径的根目录。⚠ 该目录**必须已存在**，否则首次调用抛 `RuntimeError`（根路径不存在） |
 
-**向量库** → `kit.zvec_kit`
-
-| 环境变量 | 默认值 | 作用 |
-|----------|--------|------|
-| `ZVEC_DATA_DIR` | `./data/zvec` | Collection 根目录 |
-| `ZVEC_DEFAULT_METRIC` | `cosine` | 默认距离度量（`cosine` / `l2` / `ip`） |
-| `ZVEC_QUERY_THREADS` | `None`（自适应） | 查询线程数 |
-| `ZVEC_OPTIMIZE_THREADS` | `None`（自适应） | 索引构建线程数 |
-| `ZVEC_MEMORY_LIMIT_MB` | `None`（自适应） | 内存软上限 |
-| `ZVEC_LOG_DIR` | `./logs/zvec` | zvec 引擎独立日志目录 |
-| `ZVEC_LOG_LEVEL` | `warn` | zvec 引擎日志级别 |
-
 **AI** → `kit.ai`
 
 | 环境变量 | 默认值 | 作用 |
@@ -244,14 +230,6 @@ SQLITE_DB_PATH=./data/sqlite.db
 | `KIT_AI_CHAIN_TIMEOUT` | 未设置 | 全局整链预算（秒）= 门面同步等待上限。⚠ **不是 `Settings` 字段**，由代码直读 `os.environ`，无类型/范围校验，非法值仅告警后回退 |
 | *（密钥，变量名由档案决定）* | 无 | 名字写在 `ai_models.json` 各档案的 `api_key` 字段（如 `SILICONFLOW_API_KEY`），值放 `.env` 或系统环境变量。未配置的档案会被剔除出候选链；该类型全部未配置则调用失败 |
 
-**MCP** → `kit.mcp_kit`
-
-| 环境变量 | 默认值 | 作用 |
-|----------|--------|------|
-| `MCP_SERVERS_CONFIG_PATH` | `./config/mcp_servers.json` | 服务器档案位置 |
-| `MCP_CALL_TIMEOUT` | `60`（1–600） | 档案未声明 `timeout` 时的调用超时 |
-| *（令牌，变量名由档案决定）* | 无 | 名字写在 `mcp_servers.json` 各服务器的 `token_env` 字段（如 `AMINER_TOKEN`）；档案声明了却两处都未配置时抛 `McpKitError` |
-
 **MinerU** → `kit.mineru_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -274,6 +252,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`
 
 | 环境变量 | 默认值 | 作用 |
@@ -287,7 +277,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`**——所以档案文件可以安全入库，密钥留在环境里 |
+| ③ 档案声明变量 | **动态**，名字写在 JSON 里 | AI 的 `api_key` | **名字进 JSON、值进 `.env`**——所以档案文件可以安全入库，密钥留在环境里 |
 | ④ 第三方库变量 | 由依赖库定义 | `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`（不覆盖显式设置） |
 
 ### 密钥解析优先级
@@ -295,7 +285,6 @@ SQLITE_DB_PATH=./data/sqlite.db
 | 能力 | 解析顺序 | 全部缺失时 |
 |------|----------|------------|
 | AI | 真实环境变量 > 项目根 `.env`（首次加载档案时经 `load_dotenv(override=False)` 注入 `os.environ`） | 该档案被剔除出候选链；该类型无可用档案则调用报 `AIAggregateError` |
-| MCP | `os.environ` > 项目根 `.env`（kit 自行解析文件） | 抛 `McpKitError` |
 | MinerU | 仅 `Settings`（`.env` / 真实环境变量） | 精准解析接口抛 `MinerUError` |
 
 > AI 的 `load_dotenv(override=False)` 表示已存在的真实环境变量不会被 `.env` 覆盖——生产用容器 / 系统环境变量注入时，可以放心保留开发用的 `.env`。
@@ -304,13 +293,13 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 | 改动内容 | 生效时机 |
 |----------|----------|
-| `LOG_*`、`DB_*`、`MYSQL_*`、`REDIS_*`、`FILE_STORAGE_ROOT`、`ZVEC_*`、`MINERU_*`、`MARKER_MODE` | `get_settings()` 带 `lru_cache`，进程内首次读取后固定 → **重启进程**（或调用 `AI.reload_config()`，它会顺带清空该缓存） |
+| `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` 应用 → 改动需**重启进程**重新导入模块 |
+| `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)` |
 | `KIT_AI_CHAIN_TIMEOUT` | 每次调用现读 `os.environ` → 改 `os.environ` 立即生效；写在 `.env` 里的新值要等下一次档案加载 |
-| MCP token | 每次调用现读 `os.environ` 并回退解析 `.env` → **改 `.env` 立即生效，无需重启** |
 
 ---
 
@@ -704,7 +693,7 @@ page = qb.paginate(page=1, per_page=20)            # {"items", "total", ...}
 ## kit.ai —— AI 多模型服务池
 
 安装：`pip install "sdpy-kit[ai]"`
-档案：项目根 `config/ai_models.json`（见文末「AI / MCP 档案文件」）
+档案：项目根 `config/ai_models.json`（见文末「AI 档案文件」）
 
 ### 1. 同步门面 `AI`（推荐）
 
@@ -784,46 +773,6 @@ from kit.ai.exceptions import (
 | `AIAggregateError` | 全部候选失败或整链预算耗尽；`tried`、`statuses`、`last_error`、`budget_exhausted` |
 | `AIResponseError` | 响应结构解析失败、流式数据无法解析 |
 
----
-
-## kit.mcp_kit —— 通用 MCP 客户端
-
-安装：`pip install "sdpy-kit[mcp]"`
-档案：项目根 `config/mcp_servers.json`；token 值放 `.env`（档案里只写环境变量名）
-
-```python
-from kit.mcp_kit import McpKit
-
-tools = McpKit.list_tools("aminer")                                  # [{name, description}]
-result = McpKit.call_tool("search_paper_by_title", {"title": "水声通信", "size": 10})
-print(result.data, result.elapsed_ms)
-
-# 直连临时服务器（不经档案）
-r = McpKit.call_tool_url("https://example.com/mcp", "query", {}, token="...")
-
-# 异步环境 / 一次握手复用多次调用
-async with McpKit.session("aminer") as call:
-    r1 = await call("search_paper_by_title", {"title": "A"})
-    r2 = await call("get_papers_info", {"id": "1"})
-```
-
-| 方法 | 说明 |
-|------|------|
-| `list_tools(server=None) -> list[dict]` | 工具发现；`server=None` 用档案 `default_server` |
-| `call_tool(name, arguments, *, server=None) -> McpToolResult` | 同步短连接调用（主路径） |
-| `call_tool_async(name, arguments, *, server=None) -> McpToolResult` | 异步版；FastAPI 等已有事件循环的进程内必须用 |
-| `session(server=None)` | `async with` 长连接复用，产出 `call(name, arguments)` 协程函数 |
-| `call_tool_url(url, name, arguments, *, token=None, transport="streamable-http", timeout=None) -> McpToolResult` | 直连临时服务器，不经档案 |
-
-| 类型 | 说明 |
-|------|------|
-| `McpToolResult(server, tool, elapsed_ms, data)` | 调用结果；`data` 为 JSON 解析后对象，非 JSON 文本降级为字符串 |
-| `McpKitError(message, *, detail=None)` | 业务失败时 `detail` 为服务端原始响应；连接失败时为最后一次传输层错误 |
-
-> 传输方式仅 `streamable-http`（默认）与 `sse`；档案配 `fallback_url` 时主端点传输层失败会自动回退（业务失败不回退）。
-
----
-
 ## kit.redis_kit —— Redis 工具
 
 安装：`pip install "sdpy-kit[redis]"`
@@ -1059,42 +1008,12 @@ MarkerKit.shutdown()   # 释放模型与推理服务（幂等）
 > `mode` 缺省时不写入配置，交由 marker 按设备自动选择；首次使用会下载模型权重（默认走 `MARKER_HF_ENDPOINT` 镜像）。
 > 非 NVIDIA 平台完整 VLM 能力（公式 / 扫描页 OCR）需 llama.cpp 的 `llama-server`，否则用 `disable_ocr=True` 跳过。
 
----
-
-## kit.zvec_kit —— 本地向量库
-
-安装：`pip install "sdpy-kit[zvec]"`
-
-```python
-from kit.zvec_kit import ZvecKit
-
-schema = ZvecKit.make_text_embedding_schema("docs", dim=768)
-ZvecKit.create_collection("docs", schema)
-ZvecKit.insert("docs", {"id": "d1", "vectors": {"embedding": [0.1] * 768}, "fields": {"year": 2024}})
-
-results = ZvecKit.vector_query("docs", field="embedding", vector=[0.3] * 768, topk=10)
-ZvecKit.flush("docs")
-```
-
-| 分组 | 方法 |
-|------|------|
-| 连接 | `connect() -> bool`、`close() -> None`、`is_connected() -> bool` |
-| Collection | `create_collection(name_or_path, schema) -> Collection`、`open_collection(name_or_path)`、`collection_exists(name_or_path) -> bool`、`list_collections() -> list[str]`、`destroy_collection(name_or_path) -> bool`、`get_schema(name_or_path)`、`get_stats(name_or_path) -> dict` |
-| 文档 CRUD | `insert(name_or_path, data) -> str`、`insert_multi(name_or_path, data_list) -> list[str]`、`upsert(name_or_path, data) -> str`、`update(name_or_path, data) -> str`、`fetch(name_or_path, ids, *, include_vector=True) -> dict`、`delete(name_or_path, ids) -> bool`、`delete_by_filter(name_or_path, filter_expr) -> bool`、`count(name_or_path) -> int`、`flush(name_or_path) -> None` |
-| 检索 / 维护 | `vector_query(name_or_path, *, field, vector, topk=10, filter_expr=None, include_vector=False) -> list[dict]`、`optimize(name_or_path) -> None` |
-| Schema | `make_text_embedding_schema(name, dim, metric=None, extra_fields=None) -> CollectionSchema` |
-
-> 文档字典键：`id`（必需）、`vectors`（可选）、`fields`（可选）；`filter_expr` 中相等用单等号 `=`。
-> 异常：`ZvecError`（独立于 `kit.db` 的 `DBError` 体系）。
-
----
-
-## kit.wx_article_kit —— 微信公众号文章抓取存储
+## kit.crawl.wx_article_kit —— 微信公众号文章抓取存储
 
 零第三方依赖（标准库 `urllib` + 内置 HTML→Markdown 转换器），**无需 extra**，按需 import：
 
 ```python
-from kit.wx_article_kit import WxArticleKit
+from kit.crawl.wx_article_kit import WxArticleKit
 
 # 抓取解析（不落盘）
 result = WxArticleKit.fetch("https://mp.weixin.qq.com/s/xxxx")
@@ -1118,7 +1037,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,19 +1046,72 @@ WxArticleKit.save(url, "./output", "12345", write_meta=True)
   `ArticleInfo.publish_time` 与 `meta.json` 内仍为 ISO 8601（结构化数据）。
 - 无登录态抓取：命中微信风控（环境异常 / 访问过于频繁）时返回 `ok=False` + 原因，不破解验证码；
   抓取或图片下载失败不抛异常，单张图片失败时正文保留原远程 URL。
+- 模型与 `WebArticleKit` 共用 `kit.crawl.article_models`（`ArticleInfo` 含 `source` / `site_host`）；
+  失败时 `reason` 为类型化分类（微信常用 `risk_control` / `no_content` / `fetch_failed`）。
 - 同名子目录**覆盖写**（不追加序号）；`file_name` 带 `.md` 后缀会自动去除，为空则抛 `ValueError`。
 
 ---
 
-## AI / MCP 档案文件
+## kit.crawl.web_article_kit —— 通用网页文章抓取存储
+
+可选依赖（`trafilatura`），需安装 `pip install "sdpy-kit[web-article]"`，按需 import：
+
+```python
+from kit.crawl.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.crawl.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.crawl.article_models`，与
+`WxArticleKit` **共用同一套**。
+
+质量信号（均不改变成功语义）：
+
+| 字段 | 取值 / 含义 |
+|---|---|
+| `reason` | 失败时的类型化分类：`unsupported_source` / `fetch_blocked` / `fetch_failed` / `no_content` / `risk_control`（成功为空串） |
+| `warnings` | **非致命**抽取自检提示（`tuple[str, ...]`）：正文疑似过短、页面含图片但产物无图；同时写入 warning 日志 |
+
+标题统一去除站点后缀（如 CSDN 的 `标题-CSDN博客`）；刻意不做「与页面 h1 择优」（h1 可能是导航文案）。
+
+---
+
+## AI 档案文件
 
-AI 与 MCP 功能需要在项目根目录提供两个 JSON 档案文件：
+AI 功能需要在项目根目录提供 `config/ai_models.json`（chat / embedding / rerank / image 四类型多厂商模型档案）。
 
-- `config/ai_models.json` —— chat / embedding / rerank / image 四类型多厂商模型档案
-- `config/mcp_servers.json` —— MCP 服务器档案
 
 文件缺失时，首次使用相应功能会报错，**报错信息中附带可直接复制的最小模板**；
-其中 `api_key` / `token_env` 字段填写环境变量名，真实密钥配置在 `.env`。
+其中 `api_key` 字段填写环境变量名，真实密钥配置在 `.env`。
 
 ### ai_models.json 可选字段
 
@@ -1159,22 +1131,6 @@ AI 与 MCP 功能需要在项目根目录提供两个 JSON 档案文件：
 全候选状态码一致时透传（如整链 429 可用 `exc.status_code == 429` 判定），
 429 的 `Retry-After` 解析后挂于 `exc.retry_after`（冷却钳制 5–300s）。
 
-### mcp_servers.json 最小模板
-
-```json
-{
-  "default_server": "aminer",
-  "servers": {
-    "aminer": {
-      "transport": "streamable-http",
-      "url": "https://mcp.aminer.cn/mcp",
-      "token_env": "AMINER_TOKEN",
-      "timeout": 60
-    }
-  }
-}
-```
-
 ## License
 
 MIT