sdpy-kit 0.5.3__tar.gz → 0.6.1__tar.gz

{sdpy_kit-0.5.3 → sdpy_kit-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.5.3
+Version: 0.6.1
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -18,7 +18,7 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.13
 Requires-Dist: cryptography>=46.0.7
-Requires-Dist: pydantic-settings>=2.15.0
+Requires-Dist: pydantic-settings>=2.16.1
 Requires-Dist: pydantic>=2.14.1
 Requires-Dist: sqlalchemy~=2.0.54
 Requires-Dist: sqlmodel>=0.0.48
@@ -30,7 +30,7 @@ Requires-Dist: docxtpl>=0.20.2; 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'
-Requires-Dist: laya>=0.4.6; extra == 'all'
+Requires-Dist: laya>=0.4.12; extra == 'all'
 Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
 Requires-Dist: marker-pdf>=2.0.0; extra == 'all'
 Requires-Dist: numpy>=2.5.4; extra == 'all'
@@ -53,7 +53,7 @@ Provides-Extra: docx-parse
 Requires-Dist: rc-docparser>=0.2.2; extra == 'docx-parse'
 Provides-Extra: laya
 Requires-Dist: huggingface-hub<2,>=1.5; extra == 'laya'
-Requires-Dist: laya>=0.4.6; extra == 'laya'
+Requires-Dist: laya>=0.4.12; extra == 'laya'
 Provides-Extra: marker
 Requires-Dist: marker-pdf>=2.0.0; extra == 'marker'
 Provides-Extra: md2doc
@@ -78,7 +78,7 @@ Description-Content-Type: text/markdown
 
 SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 
-- **统一数据库访问层**：PostgreSQL / MySQL / SQLite，三个 Kit API 完全一致，切换数据库只改一行 import；
+- **统一数据库访问层**：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 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
 
@@ -101,9 +101,11 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.docs.mineru_kit` | `MinerUKit` | MinerU 文档解析（精准 + Agent 轻量） | `mineru` |
 | `kit.docs.marker_kit` | `MarkerKit` | 本地解析（PDF / 图片 → Markdown + Images） | `marker` |
 | `kit.laya_kit` | `LayaKit` | 类型化决策：choice / score / noul，返回判断结果 + 置信度 | `laya` |
-| `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（两 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
+| `kit.crawl.article_models` | `ArticleInfo` / `ArticleResult` / `SavedOutput` 等 | 文章抓取通用模型（三个 `*ArticleKit` 共用，含 `reason` 分类与非致命 `warnings`） | 无 |
+| `kit.crawl.article_io` | `resolve_stem` / `save_article` 等 | 落盘公共层（目录命名 / 图片本地化 / YAML 头 / `meta.json`），三个 `*ArticleKit` 共用 | 无 |
 | `kit.crawl.wx_article_kit` | `WxArticleKit` | 微信公众号文章 → Markdown + 图片转存 | 无 |
 | `kit.crawl.web_article_kit` | `WebArticleKit` | 通用网页文章 → Markdown + 图片转存（**不含微信**，微信请用 `WxArticleKit`；明确支持头条） | `web-article` |
+| `kit.crawl.deepseek_kit` | `DeepSeekKit` | DeepSeek Search / Fetch API：网页搜索 + 单页抓取转 Markdown（`save` 与另两个 Kit 同契约） | 无（需 `DEEPSEEK_API_KEY`） |
 
 ## 安装
 
@@ -336,7 +338,7 @@ from kit.db import session_scope, transactional, DBError    # 推荐
 from kit import session_scope, transactional, DBError       # 等价
 ```
 
-### 1. 三个数据库 Kit（24 个共享方法 API 完全一致）
+### 1. 三个数据库 Kit（31 个共享方法 API 完全一致）
 
 | 类 | 导入 | 数据库 | extra |
 |----|------|--------|-------|
@@ -344,7 +346,7 @@ from kit import session_scope, transactional, DBError       # 等价
 | `PgKit` | `from kit.db.pg_kit import PgKit` | PostgreSQL | `pg` |
 | `MySqlKit` | `from kit.db.mysql_kit import MySqlKit` | MySQL | `mysql` |
 
-**共有方法（23 个，全部为 classmethod，内部自动提交）**
+**共有方法（31 个，全部为 classmethod；`raw_*` 内部自动提交，`build_raw_*` 只拼装不执行）**
 
 | 分组 | 方法 | 说明 |
 |------|------|------|
@@ -365,7 +367,11 @@ from kit import session_scope, transactional, DBError       # 等价
 | 原生 SQL | `execute(sql, params=None) -> int` | 原生写入，返回影响行数；`params` 传**字典列表**时批量执行（executemany，行键集须一致、行值须为标量、空列表返回 0） |
 | 原生 SQL | `prepare_statement(sql, params=None) -> (语句, dict \| None)` | **模块级函数**（`from kit.db import prepare_statement`）：构造可在**自有事务**内 `session.execute(stmt, bound)` 的语句，支持 `IN :ids`，调用方无须 import `sqlalchemy` |
 | 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
-| 原生表 | `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
+| 原生表 | `raw_insert(table_name, data, *, ignore_conflict=False) -> int` | 插入一行；`ignore_conflict=True` 幂等（PG/SQLite `ON CONFLICT DO NOTHING`、MySQL `INSERT IGNORE`） |
+| 原生表 | `raw_update(table_name, data, where, params=None) -> int` | 按 `where`（不含 `WHERE`）更新；启用审计填充时自动补 `updated_*` |
+| 原生表 | `raw_touch(table_name, where, params=None) -> int` | **0.6.0**：只刷新 `updated_*`（需先 `enable`；表无该列抛 `DBError`） |
+| 原生表 | `raw_delete(table_name, where, params=None) -> int` | **0.6.0**：条件删除（`where` 必填） |
+| 原生表 | `build_raw_insert / build_raw_update / build_raw_touch / build_raw_delete` | **0.6.0**：只拼装不执行，返回 `(语句, 参数)`，供**自有事务**内 `session.execute(*builder(...))` |
 | 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
 | 事务 | `transaction()` | 事务上下文管理器，`with PgKit.transaction() as session:` |
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
@@ -596,7 +602,90 @@ finally:
 > 相似度换算建议：SQLite 仅支持 L2，若向量入库前已**归一化**，则 `cos = 1 − L2²/2`；
 > PG 可直接用 `distance_type="COSINE"`。
 
-### 3. CRUDBase（配合 session_scope，不自动提交）
+### 3. 审计字段自动填充与软删除过滤（默认关闭）
+
+`AuditConfig.enable(...)` 后，kit 的写入口自动补齐审计字段；`set_soft_delete_filter(True)`
+后查询自动只看未删除记录。**两项默认都关闭**，不调用时行为与旧版完全一致。
+
+```python
+from kit.db import AuditConfig, PgKit
+
+AuditConfig.enable(user_resolver=get_current_userid)   # 启动时调用一次
+AuditConfig.set_soft_delete_filter(True)               # 可选：查询过滤软删除
+```
+
+填充字段（默认列名 + 内置别名）：
+
+| 槽位 | 默认列名 | 内置别名 | 说明 |
+|------|----------|----------|------|
+| `created_at` | `created_at` | `create_time` | 创建时间 |
+| `created_by` | `created_by` | — | 创建人 |
+| `updated_at` | `updated_at` | `update_time` | 更新时间 |
+| `updated_by` | `updated_by` | — | 更新人 |
+| `deleted` | `deleted` | — | `0` 正常 / `1` 删除 |
+
+**内置别名无需配置**：表里的时间列若叫 `create_time` / `update_time`，同样会被识别；
+两套列同时存在时两列都填（同值）。
+
+判定只有两条（同时满足才填）：**表中存在该列** + **本次写入数据中该字段为空**
+（`None` / 空串 / 纯空白；`0` 与 `False` 不算空）。显式非空值一律保留，
+**不存在覆盖语义**；「当前值」指本次写入的数据，不是数据库已存值。
+
+| 动作 | `created_at` / `create_time` | `updated_at` / `update_time` | `deleted` |
+|------|------------------------------|------------------------------|-----------|
+| INSERT | 空才填 | 空才填（与 created 同值） | 空才填 `0`（字符串列填 `"0"`） |
+| UPDATE | **不参与** | 空才填 | **不参与** |
+
+落点：ORM flush（`before_flush`）、`CRUDBase.update_multi` / `upsert`、
+`raw_insert` / `raw_update`。**`execute()` 手写 SQL 与批量 executemany 不填充**。
+
+```python
+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)
+```
+
+自定义字段名（列名与约定完全不同时）：
+
+```python
+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` 填充，不影响写入。
+
+**原生写工具（0.6.0）**：`raw_insert` / `raw_update` / `raw_touch` / `raw_delete` 自带事务；
+`build_raw_*` 只拼装（返回 `(语句, 参数)`），供 `with Kit.transaction() as session:` 内使用：
+
+```python
+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，不自动提交）
 
 ```python
 from kit.db import CRUDBase, session_scope
@@ -628,7 +717,7 @@ with session_scope() as session:          # 正常退出提交、异常回滚
 
 > 约定：`SQLiteKit / PgKit / MySqlKit` 方法自动提交；`CRUDBase` 方法**不提交**，事务边界由外层 `session_scope` 或 `@transactional` 决定。
 
-### 4. 引擎 / 会话 / 事务 / 异常
+### 5. 引擎 / 会话 / 事务 / 异常
 
 | 符号 | 签名 | 说明 |
 |------|------|------|
@@ -655,7 +744,7 @@ def transfer(session: Session, from_id: int, to_id: int, amount: float) -> None:
     ...
 ```
 
-### 5. 模型混入类与查询构建器
+### 6. 模型混入类与查询构建器
 
 ```python
 from sqlalchemy import BigInteger
@@ -1064,35 +1153,41 @@ 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/
+# 抓取并存储：<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)
 
-# 需要结构化元信息时再产出 meta.json（默认不产出）
-WxArticleKit.save(url, "./output", "12345", write_meta=True)
+# 不传 file_name：目录按本地时间 yymmddhhmmss 自动命名
+WxArticleKit.save(url, "./output")
+
+# 不需要 meta.json 时显式关闭
+WxArticleKit.save(url, "./output", "12345", write_meta=False)
 ```
 
 | 方法 | 说明 |
 |------|------|
 | `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` |
+| `save(url, output_dir, file_name=None, write_meta=True, timeout=20.0) -> SavedOutput` | 抓取并存储到 `<output_dir>/<stem>/`；结果对象字段 `ok` / `error` / `output_dir` / `md_path` / `images_dir` / `title` / `images_saved` / `reason` / `warnings` |
 
-落盘结构：
+落盘结构（三个 `*ArticleKit` 统一由 `kit.crawl.article_io` 完成）：
 
 ```
-<output_dir>/<file_name>/
-├── <file_name>.md     # 正文 Markdown（YAML 头：title / author / publish_time / source / source_url）
-├── images/            # 图片转存（NNN.ext，正文引用已本地化）
-└── meta.json          # 可选：结构化元信息（write_meta=True 时产出）
+<output_dir>/<stem>/
+├── <stem>.md      # 正文 Markdown（YAML 头：title / author / publish_time / source / source_url）
+├── images/        # 图片转存（NNN.ext，正文引用已本地化）
+└── meta.json      # 结构化元信息（默认产出；write_meta=False 关闭）
 ```
 
-- 元信息默认随 Markdown 的 YAML 头落盘（头部 `publish_time` 为中文日期，如 `2026年8月4日`）；
+- `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` 带 `.md` 后缀会自动去除，为空则抛 `ValueError`。
+- 显式 `file_name` 时同名子目录**覆盖写**（不追加序号）；省略时按时间自动命名，同秒追加 `-2`…；
+  `file_name` 带 `.md` 后缀会自动去除，显式传空串则抛 `ValueError`。
 
 ---
 
@@ -1108,21 +1203,21 @@ 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/
+# 抓取并存储：<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)
 
-# 需要结构化元信息时再产出 meta.json（默认不产出）
-WebArticleKit.save(url, "./output", "12345", write_meta=True)
+# 不传 file_name：目录按本地时间 yymmddhhmmss 自动命名
+WebArticleKit.save(url, "./output")
 ```
 
 | 方法 | 说明 |
 |------|------|
 | `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` 一致 |
+| `save(url, output_dir, file_name=None, write_meta=True, timeout=20.0) -> SavedOutput` | 抓取并存储到 `<output_dir>/<stem>/`；字段与 `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` 渲染为中文日期）。
+落盘结构与 `WxArticleKit` 完全一致（`<stem>.md` + `images/` + `meta.json`）：
+`<stem>.md` 的 YAML 头为 `title / author / publish_time / source / source_url`（`publish_time` 渲染为中文日期）。
 
 **站点覆盖范围**（规则表只允许「转交」与「接口适配」两类条目，不做逐站 DOM 补丁）：
 
@@ -1142,11 +1237,52 @@ WebArticleKit.save(url, "./output", "12345", write_meta=True)
 
 | 字段 | 取值 / 含义 |
 |---|---|
-| `reason` | 失败时的类型化分类：`unsupported_source` / `fetch_blocked` / `fetch_failed` / `no_content` / `risk_control`（成功为空串） |
+| `reason` | 失败时的类型化分类：`unsupported_source` / `fetch_blocked` / `fetch_failed` / `no_content` / `risk_control` / `auth_failed` / `rate_limited` / `config_missing`（成功为空串） |
 | `warnings` | **非致命**抽取自检提示（`tuple[str, ...]`）：正文疑似过短、页面含图片但产物无图；同时写入 warning 日志 |
 
 标题统一去除站点后缀（如 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 重试
+```
+
+```python
+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")
+```
+
+| 方法 | 说明 |
+|------|------|
+| `search(query, count=10, need_content=False, ori_question=None, localization=None, timeout=None, retries=None) -> SearchResult` | 返回 `ok` / `error` / `reason` / `items`（`SearchItem` 元组）/ `warnings`；`SearchItem.to_dict()` 可直接 JSON 化 |
+| `fetch(url, timeout=None, retries=None) -> ArticleResult` | 与 `WebArticleKit.fetch` 同构（`info` / `markdown` / `reason` / `warnings`） |
+| `save(url, output_dir, file_name=None, write_meta=True, timeout=None, retries=None) -> SavedOutput` | 落盘结构与两个 `*ArticleKit` 完全一致 |
+
+失败 `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 档案文件