sdpy-kit

SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：

• 统一数据库访问层：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；内置审计字段自动填充（created_* / updated_* / deleted）与软删除查询过滤；
• AI 多模型服务池：chat / embedding / rerank / image 四类能力，多厂商候选链 + 故障自动转移；
• 工具集：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。

要求 Python 3.13+

模块与方法入口

安装

pip install sdpy-kit            # 基础版：config/log + kit.db 核心（SQLite 常规操作零额外依赖）
# 或
uv add sdpy-kit

可选能力按 extras 按需安装（均为延迟导入，不装不影响基础使用，缺依赖时报错会提示安装命令）：

配置（.env）

kit 通过 pydantic-settings 读取项目根目录 .env；同名真实环境变量优先于 .env。全部变量都有默认值，按需覆盖即可。

最小样例 .env

# 日志（可选）
LOG_LEVEL=INFO
LOG_TO_FILE=false

# 数据库（三选一，切换只改 DEFAULT_DB_TYPE：postgresql / mysql / sqlite）
DEFAULT_DB_TYPE=sqlite
SQLITE_DB_PATH=./data/sqlite.db
# DB_HOST=localhost
# DB_PORT=5432
# DB_DATABASE=postgres
# DB_USER=admin
# DB_PASSWORD=
# MYSQL_PORT=3306
# MYSQL_DATABASE=mydb
# MYSQL_USER=root
# MYSQL_CHARSET=utf8mb4

# 按需启用以下能力
# REDIS_HOST=localhost
# REDIS_PORT=6379
# REDIS_DB=0
# REDIS_PASSWORD=
# FILE_STORAGE_ROOT=./data

# AI：档案路径 + 你为各模型档案自定的密钥变量名（变量名在 ai_models.json 里声明）
# AI_MODELS_CONFIG_PATH=./config/ai_models.json
# SILICONFLOW_API_KEY=sk-xxxxxx

# 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=

# 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.crawl.article_models、kit.crawl.article_io、kit.common_kit、kit.docs.docx_kit、kit.docs.md2doc_kit、kit.license_kit）不读取任何环境变量。

基础与日志（影响 kit.config 及所有模块的日志输出）

数据库 → kit.db、SQLiteKit / PgKit / MySqlKit

Redis → kit.redis_kit

文件存储 → kit.file_kit

AI → kit.ai

MinerU → kit.docs.mineru_kit

Marker → kit.docs.marker_kit

这四项由 kit 在导入 marker 之前经 os.environ.setdefault 应用：仅当用户未显式设置对应环境变量时生效，不覆盖显式配置。

Laya → kit.laya_kit

LAYA_HF_* 同样由 kit 在导入 laya 之前经 os.environ.setdefault 应用，不覆盖显式配置； LAYA_MODEL / LAYA_DEVICE 由 Settings 读取（进程内缓存，改后需重启进程）。

DeepSeek Search / Fetch → kit.crawl.deepseek_kit

文章抓取长度自检 → kit.crawl.wx_article_kit / web_article_kit / deepseek_kit

云 OCR（任何 ocr="hosted" 的转换）→ kit.docs.anydoc_kit

环境变量的四类来源

密钥解析优先级

AI 的 load_dotenv(override=False) 表示已存在的真实环境变量不会被 .env 覆盖——生产用容器 / 系统环境变量注入时，可以放心保留开发用的 .env。

改了配置何时生效

kit.config —— 配置与日志

from kit.config import get_settings, get_default_logger

settings = get_settings()               # Settings 单例（lru_cache，读取 .env）
logger = get_default_logger(__name__)   # 统一日志入口（禁止自建 logging handler）
logger.info("hello %s", settings.FILE_STORAGE_ROOT)

kit.db —— 统一数据库访问层

kit/__init__.py 直接重导出 kit.db 的全部公开符号，下列两种写法等价：

from kit.db import session_scope, transactional, DBError    # 推荐
from kit import session_scope, transactional, DBError       # 等价

1. 三个数据库 Kit（31 个共享方法 API 完全一致）

共有方法（31 个，全部为 classmethod；raw_* 内部自动提交，build_raw_* 只拼装不执行）

列表参数（IN）：query / execute 的 params 中值为 list/tuple/set/frozenset 时按 IN 展开，可直接写 WHERE id IN :ids（三库通用）。IN 不保证顺序；参数列表过大 应分批（PG 单语句上限 65535 参数）。

LIKE 的方言差异：SQLite 对 ASCII 不区分大小写，PostgreSQL 区分（用 ILIKE）； 跨库一致写法：LOWER(col) LIKE LOWER(:pattern)。

导出面：from kit.db import PgKit, SQLiteKit, build_pg_url, to_vector_literal, … （kit 顶层与 kit.db 导出同一套符号）。

from sqlalchemy import BigInteger
from sqlmodel import SQLModel, Field
from kit.common_kit import CommonKit
from kit.db import SQLiteKit          # 也可 from kit.db.sqlite_kit import SQLiteKit

class User(SQLModel, table=True):
    # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
    id: int = Field(default_factory=CommonKit.generate_snowflake_id,
                    primary_key=True, sa_type=BigInteger)
    name: str

SQLiteKit.connect()
SQLiteKit.create_tables([User])

user = SQLiteKit.create(User, {"name": "张三"})           # 自动提交
SQLiteKit.update(User, user.id, {"name": "李四"})
users = SQLiteKit.list(User, skip=0, limit=10, order_by="id", desc=True)

rows = SQLiteKit.query("SELECT * FROM user WHERE name = :name", {"name": "李四"})
affected = SQLiteKit.execute("UPDATE user SET name = '王五' WHERE id = :id", {"id": user.id})
rows = SQLiteKit.query("SELECT * FROM user WHERE id IN :ids", {"ids": [1, 2, 3]})   # 列表参数

with SQLiteKit.transaction() as session:                  # 多操作原子提交
    SQLiteKit.create(User, {"name": "批量一"})
    SQLiteKit.create(User, {"name": "批量二"})

切换数据库：把 import 的 SQLiteKit 换成 PgKit / MySqlKit 即可，其余代码不变。 注意三点例外：① create_raw_table 的列定义文本须按目标库方言改写；② 向量能力 三库同名同参但能力不同（可由 VECTOR_CAPABILITIES feature-detect），尤其 MySQL 侧检索不可用；③ create_vector_table 的 dims 为必填参数。

2. 向量方法（三库同名同参，能力差异化）

签名在 SQLiteKit / PgKit / MySqlKit 上完全一致；能力按后端不同（见下表）。 extra 前提：SQLite 需 sdpy-kit[sqliteai]；PG 需 sdpy-kit[pg] 且服务端已装 pgvector （create_vector_table 会自动尝试 CREATE EXTENSION）；MySQL 需 9.x（Community 即可存， 但检索需 HeatWave on OCI / MySQL AI）——建表前会校验服务端版本，低于 9.x 抛 DBError。

id_col / column（逃生口）：让自建 DDL 的向量表也能读写/检索。需要复合主键、额外约束、 分区或与既有业务表合表时，用 execute() 自建 DDL 再用这两个参数接入；SQLite 侧要求 id_col 为 rowid 别名（INTEGER PRIMARY KEY）。

exact 参数（默认 True = 禁止近似加速）：

能力差异（仅 L2 可跨库比较数值；float32 vs float64，需带容差）：

MySQL DISTANCE() / VECTOR_DISTANCE() 仅 HeatWave on OCI 与 MySQL AI 提供 （Community 实测报 1305 FUNCTION ... does not exist）；故 MySqlKit 只覆盖存储侧。

维度上限（插件侧实测 pgvector 0.8.7）：vector ≤ 16000 维；hnsw / ivfflat 索引 ≤ 2000 维；halfvec 表达式索引 ≤ 4000 维。因此 1024 维表可建 HNSW， 2560 / 4096 维表建不了。

主键与 id（三库统一）：向量表主键均为 BIGINT（SQLite 用等价的 64 位 INTEGER PRIMARY KEY）， 不使用数据库自增；ids=None 时由 Kit 用 CommonKit.generate_snowflake_id() 生成雪花 ID （18~19 位，int64）。 ⚠ 雪花 ID 超过 2^53，经 JSON 传给 JavaScript 会丢精度，需按字符串传输； 多实例部署需各自 CommonKit.configure(datacenter_id, machine_id)（默认 (1,1) 会重复）。

# SQLite（默认精确：distance 为真值 L2）
from kit.db.sqlite_kit import SQLiteKit
SQLiteKit.create_vector_table("images", 384)          # dims 必填
SQLiteKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5)
rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5, exact=False)  # 旧量化口径（不提速）

# PostgreSQL（签名相同；可选 COSINE/L2/L1/DOT/SQUARED_L2）
from kit.db.pg_kit import PgKit
PgKit.create_vector_table("images", 384)
PgKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="COSINE")
# 大表 + 自建索引时才用 exact=False（否则索引不被使用，见上表）
PgKit.execute("CREATE INDEX ON images USING hnsw (embedding vector_cosine_ops)")
rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5,
                            distance_type="COSINE", exact=False)

# MySQL（仅存储；search_vectors 抛 VectorNotSupportedError）
from kit.db.mysql_kit import MySqlKit
MySqlKit.create_vector_table("images", 384)
MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])

# 能力自省（无需 try/except）
PgKit.VECTOR_CAPABILITIES
# {'store': True, 'search': True, 'exact': True,
#  'distances': ('COSINE', 'L2', 'L1', 'DOT', 'SQUARED_L2'),
#  'distance_kind': 'true', 'fast_distance_kind': 'true',
#  'dimension_kind': 'exact'}      # MySQL='max' / SQLite=None

# 查询库列声明的维度（守卫「配置 vs 库列」用；查不到返回 None）
PgKit.vector_column_dimension("images", "embedding")   # 384

# 自建 DDL 的表：用 id_col / column 接入
PgKit.execute("CREATE TABLE my_vec (vid BIGINT PRIMARY KEY, vec vector(384))")
PgKit.insert_vectors("my_vec", [[0.1] * 384], ids=[1], id_col="vid", column="vec")
PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")

⚠ :name::type 这类 PostgreSQL 风格 cast 不被 SQLAlchemy 的 text() 识别， 请改用 CAST(:name AS type)。

两段查询范式（推荐用法）：search_vectors 只返回 [{"id", "distance"}]，载荷二次取回：

hits = SQLiteKit.search_vectors("item_vectors", query_vector, top_k=5)
rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
                       {"ids": [h["id"] for h in hits]})   # IN 不保证顺序，需按 hits 重排

自有事务内写向量（推荐：build_insert_vectors + transaction()）：

from kit.db import SQLiteKit, prepare_statement   # 无须 import sqlalchemy

with SQLiteKit.transaction() as session:          # 换成 PgKit / MySqlKit 写法相同
    stmt, bound = prepare_statement(
        "INSERT INTO docs_item (id, title) VALUES (:id, :t)", {"id": doc_id, "t": title})
    session.execute(stmt, bound)                  # 第二个值必须一并传入
    for sql, params in SQLiteKit.build_insert_vectors("docs_doc_vectors", vectors,
                                                      ids=row_ids, extra_data=metas,
                                                      id_col="rowid"):
        session.execute(*prepare_statement(sql, params))
# 正常退出统一提交；异常自动回滚（多处写入保持同一事务）

SQLite 的 DBAPI 变体（raw_connection() 支持 :name 命名参数）：

conn = SQLiteKit.raw_connection()          # 调用方负责 commit / close
try:
    for sql, params in SQLiteKit.build_insert_vectors("item_vectors", vectors,
                                                      ids=row_ids, extra_data=metas):
        conn.executemany(sql, params)
    conn.commit()
finally:
    conn.close()

⚠ 两点约束：① build_insert_vectors 输出为 :name 风格，PG / MySQL 的原生 DBAPI 不支持 （psycopg2 / pymysql 需 %(name)s），只能经 transaction() 的 session 执行； ② SQLite 上持有未提交写事务时再调 kit 的自提交方法（如 insert_vectors）会因另一个连接 拿不到写锁而失败（OperationalError: database is locked，约 6.4s 后才报错）—— 把写入并入同一个 transaction()（如上）即可避免。

相似度换算建议：SQLite 仅支持 L2，若向量入库前已归一化，则 cos = 1 − L2²/2； PG 可直接用 distance_type="COSINE"。

3. 审计字段自动填充与软删除过滤（默认关闭）

AuditConfig.enable(...) 后，kit 的写入口自动补齐审计字段；set_soft_delete_filter(True) 后查询自动只看未删除记录。两项默认都关闭，不调用时行为与旧版完全一致。

from kit.db import AuditConfig, PgKit

AuditConfig.enable(user_resolver=get_current_userid)   # 启动时调用一次
AuditConfig.set_soft_delete_filter(True)               # 可选：查询过滤软删除

填充字段（默认列名 + 内置别名）：

内置别名无需配置：表里的时间列若叫 create_time / update_time，同样会被识别； 两套列同时存在时两列都填（同值）。

判定只有两条（同时满足才填）：表中存在该列 + 本次写入数据中该字段为空 （None / 空串 / 纯空白；0 与 False 不算空）。显式非空值一律保留， 不存在覆盖语义；「当前值」指本次写入的数据，不是数据库已存值。

落点：ORM flush（before_flush）、CRUDBase.update_multi / upsert、 raw_insert / raw_update。execute() 手写 SQL 与批量 executemany 不填充。

PgKit.raw_insert("chat_session", {"id": 1, "title": "t"})
# → 自动补 created_at/created_by/updated_at/updated_by 与 deleted=0

PgKit.raw_update("chat_session", {"title": "t2"}, "id = :id", {"id": 1})
# → 只刷 updated_at / updated_by；where 的值全部走绑定参数

PgKit.raw_get_by("chat_session", "id", 1)   # 过滤开启时自动排除已删除行

with AuditConfig.include_deleted():         # 需要读已删除记录时临时绕过
    PgKit.get(Model, 1)

自定义字段名（列名与约定完全不同时）：

AuditConfig.set_fields({"created_at": "create_on", "deleted": "del_flag"})
AuditConfig.fields()          # 查看当前「槽位 → 实际列名」
AuditConfig.set_fields(None)  # 恢复默认

约定与局限：

• set_fields 的列名必须是合法标识符（字母 / 数字 / 下划线，不以数字开头）， 否则立即 ValueError——列名会被拼进 SQL 的标识符位置。
• deleted 支持整数列（填 0）与字符串列（填 "0"，VARCHAR / CHAR / TEXT）； boolean 列不支持（会报类型错误）。
• 查询过滤严格等值 deleted = 0（字符串列 "0"）；NULL 不视为未删除，历史数据需自行回填。
• 写方法与 query() 手写 SQL 不追加过滤条件；upsert 的冲突回查跳过过滤。
• user_resolver 返回 None / 空串或抛异常时跳过 *_by 填充，不影响写入。

原生写工具：raw_insert / raw_update / raw_touch / raw_delete 自带事务； build_raw_* 只拼装（返回 (语句, 参数)），供 with Kit.transaction() as session: 内使用：

with PgKit.transaction() as session:
    session.execute(*PgKit.build_raw_insert("docs_tag", {"id": 1}, ignore_conflict=True))
    session.execute(*PgKit.build_raw_touch("docs_item", "id = :id", {"id": 1}))

• ignore_conflict=True：PG/SQLite ON CONFLICT DO NOTHING、MySQL INSERT IGNORE （⚠ MySQL 忽略范围更宽，含数据截断告警）；冲突被忽略时返回 0。
• raw_touch：只刷新 updated_*（含别名 update_time），需先 enable；表无该列抛 DBError。
• 写入值：dict 自动编码为 JSON 文本；list 仅在 JSON 列编码，其它列抛 ValueError （避免被当作 IN 展开破坏 SQL；数组 / 向量请用字符串或 execute()）。

4. CRUDBase（配合 session_scope，不自动提交）

from kit.db import CRUDBase, session_scope

user_crud = CRUDBase(User)

with session_scope() as session:          # 正常退出提交、异常回滚
    user_crud.create(session, {"name": "张三"})
    user_crud.update(session, user_crud.get(session, 1), {"name": "李四"})

约定：SQLiteKit / PgKit / MySqlKit 方法自动提交；CRUDBase 方法不提交，事务边界由外层 session_scope 或 @transactional 决定。

5. 引擎 / 会话 / 事务 / 异常

from kit.db import transactional
from sqlmodel import Session

@transactional(retry_count=3)
def transfer(session: Session, from_id: int, to_id: int, amount: float) -> None:
    # 被装饰函数必须接受 session 参数；退出时自动提交，异常自动回滚并重试
    ...

6. 模型混入类与查询构建器

from sqlalchemy import BigInteger
from sqlmodel import Field, SQLModel

from kit.common_kit import CommonKit
from kit.db.models import TimestampMixin, SoftDeleteMixin, AuditMixin

class Article(TimestampMixin, SoftDeleteMixin, SQLModel, table=True):
    # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
    id: int = Field(default_factory=CommonKit.generate_snowflake_id,
                    primary_key=True, sa_type=BigInteger)
    title: str

查询构建器需显式从子模块导入（未进入 kit.db 顶层导出）：

from kit.db.query import QueryBuilder, QueryCache, QueryOptimizer, cached_query

qb = QueryBuilder(User, session)
active = qb.filter(User.name == "张三").all()      # 链式不可变，每步返回新实例
page = qb.paginate(page=1, per_page=20)            # {"items", "total", ...}

kit.ai —— AI 多模型服务池

安装：pip install "sdpy-kit[ai]" 档案：项目根 config/ai_models.json（见文末「AI 档案文件」）

1. 同步门面 AI（推荐）

from kit.ai.runner import AI, shutdown

text = AI.chat_complete("用一句话介绍 Python")                 # 单轮对话
hits = AI.rerank("水声通信", ["文档A", "文档B"], top_n=2)      # 重排序
url = AI.generate_image("一只在写代码的猫")                    # 文生图
AI.use("chat", "glm")                                          # 切换当前档案（进程内长期生效）
print(AI.available("chat"))                                    # 查看各档案状态快照
shutdown()                                                     # 应用退出前释放资源（幂等）

from kit.ai.runner import AI

with AI.chat_stream([{"role": "user", "content": "写一首短诗"}]) as stream:
    for token in stream:      # 逐 token 消费
        print(token, end="", flush=True)

门面仅面向同步上下文；若调用点本身在 async 函数内，请直接 await 原生异步服务，避免阻塞事件循环线程。 模块级另有 kit.ai.runner.reload_config(...)、run_sync(coro_factory, *, timeout=120.0)、shutdown()。

2. 原生异步服务

from kit.ai import (
    ChatService, EmbeddingService, RerankService, ImageService,   # 服务类
    ChatRequest, EmbeddingRequest, RerankRequest, ImageRequest,   # 请求模型
    RerankHit, ModelBuilder,                                      # 结果类型 / 构建器
)

service = ModelBuilder.build_chat()                 # 老按类型构建：build_chat / build_embedding / build_rerank / build_image
answer = await service.ask(messages)                # 或 await service.complete(prompt)
await service.close()

embedding 维度契约：ai_models.json 里 embedding 档案的 dimension 是目标向量维度 （不是模型原生维度），EmbeddingService 保证输出恒等于它：

用途：让「建表维度 = 配置维度 = 输出维度」共用一个数值—— create_vector_table(t, dims) 与 vector_column_dimension(t, col) 都取该配置值， 换用原生维度更大的模型时无需重构向量列（换模型后需全量重新入库）。

⚠ 启用候选链时，链内各档案的 dimension 必须一致：故障切换后输出维度跟随被选中档案的配置。

3. 异常

from kit.ai.exceptions import (
    AIError, AIConfigError, AIRequestError, AITimeoutError,
    AIAggregateError, AIResponseError,
)

kit.redis_kit —— Redis 工具

安装：pip install "sdpy-kit[redis]"

from kit.redis_kit import RedisKit

RedisKit.set("user:1", "clark", expire=60)
RedisKit.get("user:1")                       # -> "clark"
RedisKit.zadd("rank", {"alice": 1.0, "bob": 2.0})
RedisKit.zrange("rank", 0, -1, withscores=True)
RedisKit.close()

RedisValue = str | int | float | bytes；连接池 decode_responses=True，内置指数退避重试。

kit.file_kit —— 文件工具

相对路径均相对于 FILE_STORAGE_ROOT（默认 ./data）。

from kit.file_kit import FileKit

FileKit.write_file("docs/a.txt", "hello")         # mode="overwrite"（默认）/ "append"
text = FileKit.read_file("docs/a.txt")
path = FileKit.get_full_path("docs/a.txt")        # -> Path 绝对路径
for root, dirs, files in FileKit.walk_dir("docs"):
    print(root, files)
FileKit.open_with_default_app(path)               # 系统默认程序打开：-> "opened" / "revealed"

kit.common_kit —— 通用工具

from kit.common_kit import CommonKit

CommonKit.configure(datacenter_id=1, machine_id=1)      # 各限 1–31
CommonKit.generate_snowflake_id()                       # 63 位雪花 ID（int）
CommonKit.generate_snow_id()                            # 雪花 ID（str）
CommonKit.generate_timestamp_id()                       # 20 位时间戳 ID
CommonKit.format_current_time("yyyy-MM-dd")

kit.license_kit —— 离线授权签发与校验

零第三方依赖（cryptography 已在 base），按需 import。校验链：签名 → 产品 → 机器码 → 有效期。

from datetime import datetime, timezone
from pathlib import Path

from kit.license_kit import LicenseKit, LicensePayload, LicenseVerifier

# 1. 生成密钥对（一次性；私钥自行保管，不随包分发）
private_pem, public_pem = LicenseKit.generate_keypair()

# 2. 取机器码（16 位十六进制；仅 Windows 支持）
machine = LicenseKit.get_machine_code()
LicenseKit.export_fingerprint_file(Path("fingerprint.txt"))   # 或导出文件交给签发方
machine = LicenseKit.parse_fingerprint_file(Path("fingerprint.txt"))

# 3. 签发（离线）
payload = LicensePayload(
    product="thinktank",
    machine_code=machine,
    tier="pro",
    customer_id="C-0001",
    expires_at=datetime(2027, 12, 31, tzinfo=timezone.utc),
)
token = LicenseKit.sign(payload, private_pem)

# 4. 校验（应用启动 / 请求时）
verifier = LicenseVerifier(public_pem, Path("license.json"))
claims = verifier.verify(product="thinktank", machine_code=machine)
print(claims.tier, claims.expires_at)

LicensePayload 字段：version / product / machine_code / tier / customer_id / issued_at / expires_at。

异常：LicenseError（基类）、LicenseFormatError、LicenseSignatureError、 LicenseProductMismatchError、LicenseMachineMismatchError、LicenseExpiredError、 LicenseUnsupportedPlatformError（非 Windows 取机器码时抛）。

kit.docs.anydoc_kit —— 文档转 Markdown

安装：pip install "sdpy-kit[anydoc]"（支持 .doc .docx .ppt .pptx .xls .xlsx .csv .pdf）

from kit.docs.anydoc_kit import AnyDocKit

markdown = AnyDocKit.convert_to_md("report.docx")     # 直接转换，失败抛异常
result = AnyDocKit.convert("report.pdf")              # 安全转换，异常封装为结果对象
if result.success:
    print(result.markdown)
AnyDocKit.convert_to_file("report.docx", "out/report.md")
md = AnyDocKit.convert_bytes_to_md(file_bytes, "csv") # 字节内容直接转，无需落盘
md = AnyDocKit.convert_to_md("scan.pdf", ocr="hosted")  # 需 FIRECRAWL_API_KEY

AnyDocResult(success, markdown, file_path, source_format, error)

异常：沿用上游 anydoc.ConvertError 体系（MalformedError / NeedsOcrError 等子类可直接捕获）， AnyDocError 是该基类的别名；安全版 convert() 会把它们封装为 AnyDocResult.error。

kit.docs.docx_kit —— Word 模板动态填充

安装：pip install "sdpy-kit[docx]"

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="宋体")
DocxKit.unify_heading_color("templates/report.docx")

report = DocxReport(
    sections=(
        DocxSection(
            title="第一章 概述",
            level=1,
            blocks=(
                DocxParagraph("本章介绍项目背景。"),
                DocxTable(headers=("名称", "数值"), rows=(("甲", "1"),)),
            ),
        ),
    ),
    variables={"project": "SDPY"},
)
DocxKit.render("templates/report.docx", "out/report.docx", report)

数据结构：DocxReport(sections, variables)、DocxSection(title, level=1, blocks=())、DocxParagraph(text)、DocxListItem(text, level=1, ordered=False)、DocxTable(headers, rows=(), style=None)

kit.docs.md2doc_kit —— Markdown 转 Word / PDF / HTML

安装：pip install "sdpy-kit[md2doc]"（PDF 需系统已安装 mainfont 指定字体，默认 SimSun）

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="项目报告")
Md2DocKit.convert_md_to_pdf("report.md", mainfont="KaiTi")

dest_path=None 时输出到源文件同目录；同一源文件不支持并发转换。

图片：![alt](相对路径) 以 Markdown 源文件所在目录为基准解析，宽度等比限幅 （96dpi 还原自然尺寸、不放大），超高先分页/按版心收紧；缺图、越界路径、非图片 格式一律回落 alt 文本，不抛异常。远程地址在 PDF / Word 中不下载（回落 alt）， 在 HTML 中直出 <img src="https://…"> 交给浏览器。HTML 输出保留相对路径，需与 images/ 目录保持同层级才能在浏览器中显示。

kit.docs.mineru_kit —— MinerU 文档解析

安装：pip install "sdpy-kit[mineru]"（精准解析需 MINERU_API_KEY，Agent 轻量解析免登录）

from kit.docs.mineru_kit import MinerUKit

# 精准解析：公网 URL / 本地文件
result = MinerUKit.parse_url("https://cdn-mineru.openxlab.org.cn/demo/example.pdf", model_version="vlm")
if result.state == "done":
    zip_path = MinerUKit.download_zip(result.full_zip_url, "./output")

results = MinerUKit.parse_files(["report1.pdf", "report2.docx"])

# Agent 轻量解析（免登录、单文件 ≤10MB、≤20 页）
r = MinerUKit.agent_parse_url(url, page_range="1-10")
if r.state == "done":
    md_path = MinerUKit.download_markdown(r.markdown_url, "./output")

可选参数（model_version / is_ocr / enable_formula / enable_table / language / page_ranges / extra_formats / no_cache 等）详见各方法 docstring。 结果类型：TaskResult、BatchTaskResult、BatchFile、BatchUploadInfo、AgentParseResult、AgentUploadInfo。

kit.docs.marker_kit —— 本地解析：PDF + 图片 → Markdown + Images

安装：pip install "sdpy-kit[marker]"（依赖 marker-pdf，含 torch 等 80+ 包，体积较大；不含 [full]）

支持面：.pdf、.png、.jpg、.jpeg、.webp、.gif、.bmp。docx/pptx/xlsx/html/epub 不在支持面 （marker 侧实现依赖 weasyprint/GTK），传入会抛 ValueError。

from kit.docs.marker_kit import MarkerKit

# 落盘 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 文本（图片不落盘）
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)

# 文本层 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()   # 释放模型与推理服务（幂等）

产物：<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 镜像）。 前提条件：文本层 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/。

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))

产物：<out>/images/img-NNN-<sha1 前 10>.<ext>（按出现顺序、内容哈希命名）；无图不建空目录。 前提：中文标题依赖 w:outlineLvl 或「标题 N」样式（都没有时退化为正文）；合并单元格表格会重建为 等宽 GFM（覆盖位留空，不输出 HTML <table>）；页眉页脚/脚注不提取。纯本地，无需模型或 GPU。

kit.crawl.wx_article_kit —— 微信公众号文章抓取存储

零第三方依赖（标准库 urllib + 内置 HTML→Markdown 转换器），无需 extra，按需 import：

from kit.crawl.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>/<stem>/ 下 <stem>.md + images/ + meta.json
saved = WxArticleKit.save(url, output_dir="./output", file_name="12345")
print(saved.md_path, saved.images_saved)

# 不传 file_name：目录按本地时间 yymmddhhmmss 自动命名
WxArticleKit.save(url, "./output")

# 不需要 meta.json 时显式关闭
WxArticleKit.save(url, "./output", "12345", write_meta=False)

落盘结构（三个 *ArticleKit 统一由 kit.crawl.article_io 完成）：

<output_dir>/<stem>/
├── <stem>.md      # 正文 Markdown（YAML 头：title / author / publish_time / source / source_url）
├── images/        # 图片转存（NNN.ext，正文引用已本地化）
└── meta.json      # 结构化元信息（默认产出；write_meta=False 关闭）

• stem 不传时按本地时间 %y%m%d%H%M%S 自动命名，同秒碰撞追加 -2…-99； 显式传 file_name 时同名目录覆盖写；
• 元信息随 Markdown 的 YAML 头落盘（头部 publish_time 为中文日期，如 2026年8月4日）； 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 时同名子目录覆盖写（不追加序号）；省略时按时间自动命名，同秒追加 -2…； file_name 带 .md 后缀会自动去除，显式传空串则抛 ValueError。

kit.crawl.web_article_kit —— 通用网页文章抓取存储

可选依赖（trafilatura），需安装 pip install "sdpy-kit[web-article]"，按需 import：

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>/<stem>/ 下 <stem>.md + images/ + meta.json
saved = WebArticleKit.save(url, output_dir="./output", file_name="12345")
print(saved.md_path, saved.images_saved)

# 不传 file_name：目录按本地时间 yymmddhhmmss 自动命名
WebArticleKit.save(url, "./output")

落盘结构与 WxArticleKit 完全一致（<stem>.md + images/ + meta.json）： <stem>.md 的 YAML 头为 title / author / publish_time / source / source_url（publish_time 渲染为中文日期）。

站点覆盖范围（规则表只允许「转交」与「接口适配」两类条目，不做逐站 DOM 补丁）：

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 共用同一套。

质量信号（均不改变成功语义）：

标题统一去除站点后缀（如 CSDN 的 标题-CSDN博客）；刻意不做「与页面 h1 择优」（h1 可能是导航文案）。

kit.crawl.deepseek_kit —— DeepSeek Search / Fetch

零第三方依赖，基础安装即可用（按请求次数计费，0.005 元/次量级）。需配置 API Key：

DEEPSEEK_API_KEY=sk-xxx                 # .env 或环境变量
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_TIMEOUT=60
DEEPSEEK_MAX_RETRIES=2                  # 仅 408/429/5xx 重试

from kit.crawl.deepseek_kit import DeepSeekKit

# 1. 网页搜索（不落盘）
found = DeepSeekKit.search("DeepSeek V4 发布 site:github.com", count=5, need_content=False)
for item in found.items:
    print(item.title, item.url, item.rerank_score, item.authority)

# 2. 单页抓取（不落盘）
page = DeepSeekKit.fetch("https://api-docs.deepseek.com/zh-cn/guides/search")
print(page.info.title, page.markdown)

# 3. 抓取并存储：<output_dir>/<stem>/ 下 <stem>.md + images/ + meta.json
saved = DeepSeekKit.save(url, output_dir="./output", file_name="ds-guide")

失败 reason：auth_failed（401/402）/ fetch_blocked（403）/ no_content（404）/ rate_limited（429）/ fetch_failed（408/5xx 重试后仍失败、请求不合法）。 未配置 DEEPSEEK_API_KEY 抛 DeepSeekKitError。实现要求：

• 服务端返回的正文是重度反斜杠转义的伪 Markdown，kit 会统一反转义后再落盘；
• 该接口不返回代码块围栏，代码会被压成普通段落；图片也常缺失。 需要高保真正文（代码块、图片）请改用 WebArticleKit。

AI 档案文件

AI 功能需要在项目根目录提供 config/ai_models.json（chat / embedding / rerank / image 四类型多厂商模型档案）。

文件缺失时，首次使用相应功能会报错，报错信息中附带可直接复制的最小模板； 其中 api_key 字段填写环境变量名，真实密钥配置在 .env。

ai_models.json 可选字段

候选链切换语义（两类，勿混淆）

• 跨调用切换：AI.use() 与其它请求产生的失败冷却均只影响下一次请求——每次调用的候选计划在开始时定格；
• 一次调用内降级：本次调用按开始时定格的计划串行尝试（首帧前失败 / 首帧超时切下一候选），中途的 use / 冷却变化不影响它。

全部候选失败（或整链预算耗尽）抛 AIAggregateError（AIRequestError 子类）： 全候选状态码一致时透传（如整链 429 可用 exc.status_code == 429 判定）， 429 的 Retry-After 解析后挂于 exc.retry_after（冷却钳制 5–300s）。

License

MIT