sdpy-kit 0.6.0__tar.gz → 0.6.2__tar.gz

{sdpy_kit-0.6.0 → sdpy_kit-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.0
+Version: 0.6.2
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -80,7 +80,7 @@ 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 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
+- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
 
 > 要求 Python 3.13+
 
@@ -94,6 +94,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
 | `kit.file_kit` | `FileKit` | 文件与目录读写、移动、遍历 | 无 |
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
+| `kit.license_kit` | `LicenseKit` / `LicenseVerifier` | Ed25519 离线授权：密钥对、机器码、签发、验签（签名 → 产品 → 机器码 → 有效期） | 无 |
 | `kit.docs.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
 | `kit.docs.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
@@ -187,7 +188,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 ### 环境变量 ↔ 能力对照表
 
-> 表中未出现的模块（`kit.crawl.article_models`、`kit.common_kit`、`kit.docs.docx_kit`、`kit.docs.md2doc_kit`、`kit.crawl.wx_article_kit`、`kit.crawl.web_article_kit`）不读取任何环境变量。
+> 表中未出现的模块（`kit.crawl.article_models`、`kit.crawl.article_io`、`kit.common_kit`、`kit.docs.docx_kit`、`kit.docs.md2doc_kit`、`kit.license_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -272,6 +273,21 @@ SQLITE_DB_PATH=./data/sqlite.db
 > `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
 > `LAYA_MODEL` / `LAYA_DEVICE` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
 
+**DeepSeek Search / Fetch** → `kit.crawl.deepseek_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `DEEPSEEK_API_KEY` | 无 | Search / Fetch 鉴权 Key（与模型对话共用同一套）；缺失时调用抛 `DeepSeekKitError` |
+| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API 基础地址 |
+| `DEEPSEEK_TIMEOUT` | `60`（1–600） | 单次 HTTP 请求超时（秒） |
+| `DEEPSEEK_MAX_RETRIES` | `2`（0–5） | 408 / 429 / 5xx 重试次数（不含首次请求）；其它 4xx 不重试 |
+
+**文章抓取长度自检** → `kit.crawl.wx_article_kit` / `web_article_kit` / `deepseek_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `CRAWL_MIN_CONTENT_CHARS` | `500`（≥0） | 正文短于该长度时写入 `warnings`（非致命，不改成功语义、不截断正文）；`0` 关闭该判据 |
+
 **云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.docs.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -369,9 +385,9 @@ from kit import session_scope, transactional, DBError       # 等价
 | 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
 | 原生表 | `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_touch(table_name, where, params=None) -> int` | 只刷新 `updated_*`（需先 `enable`；表无该列抛 `DBError`） |
+| 原生表 | `raw_delete(table_name, where, params=None) -> int` | 条件删除（`where` 必填） |
+| 原生表 | `build_raw_insert / build_raw_update / build_raw_touch / build_raw_delete` | 只拼装不执行，返回 `(语句, 参数)`，供**自有事务**内 `session.execute(*builder(...))` |
 | 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
 | 事务 | `transaction()` | 事务上下文管理器，`with PgKit.transaction() as session:` |
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
@@ -505,57 +521,9 @@ 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")
 ```
 
-#### 0.2.2 行为变更（升级须知）
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B1 | `search_vectors` 新增 `exact: bool = True`，默认**精确** | SQLite 返回的 `distance` 由量化值（≈L2×255）变为**真值 L2**；需旧口径请显式 `exact=False` |
-| B2 | `filter_sql` 语义统一为**先过滤、再取 top_k** | 传 `filter_sql` 的调用返回值**变多/变全**（旧结果 ⊆ 新结果）；曾自行放大 `top_k` 兜底的调用可收紧 |
-| B3 | 默认 `distance_type` 由 `"COSINE"` 改为 `"L2"` | 依赖默认值的调用方请显式传 `distance_type="COSINE"` |
-| B4 | `create_vector_table` 的 `dims` **必填**，参数顺序为 `(table_name, dims, id_col, column, extra_cols)` | `create_vector_table("t")` 类调用需补维度；位置传 `id_col` 的调用改为关键字 |
-| B5 | MySQL 的 `search_vectors` 异常由 `NotImplementedError` 改为 `VectorNotSupportedError`（继承 `DBError`） | `except NotImplementedError` 需改为 `except VectorNotSupportedError`（或 `except DBError`） |
-
-> 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
-> `insert_vectors` 支持二维 numpy 数组与批量提交。
-
-#### 0.2.6 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| D1 | `prepare_statement` 的 `params` 支持**参数行列表**（`list[dict]`）：**原样返回该列表** → `session.execute(*prepare_statement(sql, params))` 即批量执行（executemany），与 `build_insert_vectors` 的返回形态直接对接；行键集不一致或行值含序列 → 本地可操作 `ValueError`（与 `execute` 批量形态**同一规则**） | 向后兼容：单字典 / `None` 形态行为不变；行列表形态**不做** `IN` 展开（与批量互斥） |
-| D1 | 文档：修正「自有事务」示例——0.2.5 的示例把 `build_insert_vectors` 返回的**行列表**传给了单字典形态，照抄会抛 `AttributeError: 'list' object has no attribute 'items'` | **纯文档缺陷修正**（0.2.5 示例照抄即崩） |
-| — | 文档：批量执行补充 `rowcount` 备注——忽略型写入（如 SQLite `INSERT OR IGNORE`）的冲突行不计入 `rowcount`（即 `rowcount` = 实际插入数；⚠ 仅 SQLite 实测） | 文档 |
-
-#### 0.2.5 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| — | 新增**模块级公共函数** `prepare_statement(sql, params=None) -> (语句, 归一化参数)`：供调用方在**自有事务**内执行原生 SQL（含 `IN :ids`），**调用方无须 import `sqlalchemy`**；与 `query` / `execute` 同一实现（单一事实源） | **纯新增**：`query` / `transaction` 的签名与行为**零变更**；共享方法数仍为 **24**（模块级函数不计入） |
-| — | `execute` 的 `params` 支持**字典列表**（executemany，同一语句 + N 行参数一次往返）；**空列表**不触库返回 `0` | 向后兼容：单字典 / `None` 形态行为不变；批量要求各行字典**键集一致**、行值为**标量**（与 `IN` 展开互斥），违规在本地抛可操作 `ValueError`（含行号），不触库 |
-| — | 文档：自有事务示例改用 `prepare_statement`（不再需要 `from sqlalchemy import text`）；补「批量执行」说明与约束 | 文档 |
-
-> ⚠ `:name::type` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 `text()` 识别**（0.2.5 之前亦如此），
+> ⚠ `:name::type` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 `text()` 识别**，
 > 请改用 `CAST(:name AS type)`。
 
-#### 0.2.4 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B4 | **入参自洽性校验**（`extra_data` 的键）：保留绑定名 `id` / `vec`、与 `id_col` / `column` 重复、不是合法标识符、`id_col == column` → 抛可操作的 `ValueError` | **唯一行为变更**：此前 SQLite 会**静默写坏数据**（如 `id` 列被覆盖）、PG/MySQL 报误导性错误；正常调用**零影响** |
-| — | 新增共享方法 `build_insert_vectors`（只拼装不执行，由 `BaseDbKit` 收敛 → 共享方法 23 → **24**） | 纯新增：可在**自有事务**内写向量行（见下） |
-| — | `create_vector_table` 的 `extra_cols` 支持 `{列名: 类型串}`（与 `create_raw_table` 同形） | 纯新增：既有 `[{"name","type"}]` 形态保留，两者产出 DDL 逐字一致 |
-| — | 后端差异收口：向量列占位符由 `VECTOR_PLACEHOLDER` 驱动（MySQL = `STRING_TO_VECTOR(:vec)`） | 内部整理：公开签名与行为不变 |
-| — | `SQLiteKit.insert_vectors` 的事务获取统一为 `transaction()`（与另两库同构） | 内部一致：行为等价（自成一事务并提交） |
-
-#### 0.2.3 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B6 | **`PgKit.get_table_info` 按数据库解析语义定位表**（`search_path` 解析到的那张表） | 多 schema 下同名表**不再混行**；单 schema / `public` 场景**无影响**；只接受非限定表名 |
-| — | `query` / `execute` 支持**列表参数**（`IN :ids`，三库通用） | 纯新增；`set`/`frozenset` 自动归一化为 `list` |
-| — | 新增 `SQLiteKit.encode_vector` / `decode_vector`（小端 float32） | 纯新增：可在自有事务内写向量表，见下 |
-| — | 导出面统一：`from kit.db import PgKit, MySqlKit, SQLiteKit, build_pg_url, …` | 纯新增；既有导出未删除/未改名 |
-
 **两段查询范式（推荐用法）**：`search_vectors` 只返回 `[{"id", "distance"}]`，载荷二次取回：
 
 ```python
@@ -662,13 +630,15 @@ 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` 自带事务；
+**原生写工具**：`raw_insert` / `raw_update` / `raw_touch` / `raw_delete` 自带事务；
 `build_raw_*` 只拼装（返回 `(语句, 参数)`），供 `with Kit.transaction() as session:` 内使用：
 
 ```python
@@ -941,6 +911,61 @@ CommonKit.format_current_time("yyyy-MM-dd")
 
 ---
 
+## kit.license_kit —— 离线授权签发与校验
+
+零第三方依赖（`cryptography` 已在 base），按需 import。校验链：签名 → 产品 → 机器码 → 有效期。
+
+```python
+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)
+```
+
+| 符号 | 说明 |
+|------|------|
+| `LicenseKit.generate_keypair() -> (str, str)` | 生成 Ed25519（私钥 PEM, 公钥 PEM） |
+| `LicenseKit.get_machine_code() -> str` | 本机机器码（16 位十六进制；⚠ 仅 Windows 平台） |
+| `LicenseKit.export_fingerprint_file(path) -> Path` | 导出机器指纹文件 |
+| `LicenseKit.parse_fingerprint_file(path) -> str` | 从指纹文件读回机器码 |
+| `LicenseKit.sign(payload, private_key_pem) -> str` | 签发授权 token |
+| `LicenseVerifier(public_key_pem, license_path)` | 构造验签器（绑定公钥与 license 文件） |
+| `LicenseVerifier.verify(*, product, machine_code, now=None) -> LicensePayload` | 全量校验并返回载荷；`now=None` 取 aware UTC，naive 按 UTC 解释 |
+| `LicenseVerifier.reverify() -> LicensePayload` | 用最近一次成功 `verify` 的上下文重新校验（文件被换会失败） |
+| `LicenseVerifier.file_signature` | 当前 license 文件的签名（属性） |
+
+`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`）

{sdpy_kit-0.6.0 → sdpy_kit-0.6.2}/README.md

@@ -4,7 +4,7 @@ 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 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储。
+- **工具集**：Redis / 文件 / 雪花 ID / 离线授权签发与校验 / 文档互转 / Word 模板填充 / MinerU 解析 / Marker 本地解析（PDF + 图片 → md + images/） / 离线 docx 解析（md + images/） / Laya 类型化决策 / 微信公众号文章抓取存储 / 通用网页文章抓取存储 / DeepSeek 搜索与抓取。
 
 > 要求 Python 3.13+
 
@@ -18,6 +18,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | `kit.redis_kit` | `RedisKit` | Redis string / hash / list / set / zset | `redis` |
 | `kit.file_kit` | `FileKit` | 文件与目录读写、移动、遍历 | 无 |
 | `kit.common_kit` | `CommonKit` | 雪花 ID、时间戳 ID、时间格式化 | 无 |
+| `kit.license_kit` | `LicenseKit` / `LicenseVerifier` | Ed25519 离线授权：密钥对、机器码、签发、验签（签名 → 产品 → 机器码 → 有效期） | 无 |
 | `kit.docs.anydoc_kit` | `AnyDocKit` | docx / pdf / xlsx 等 → Markdown | `anydoc` |
 | `kit.docs.docx_kit` | `DocxKit` | Word 模板动态填充（章节 / 列表 / 表格） | `docx` |
 | `kit.docs.rc_docparser_kit` | `RcDocParserKit` | 离线 docx → Markdown + Images（无模型） | `docx-parse` |
@@ -111,7 +112,7 @@ SQLITE_DB_PATH=./data/sqlite.db
 
 ### 环境变量 ↔ 能力对照表
 
-> 表中未出现的模块（`kit.crawl.article_models`、`kit.common_kit`、`kit.docs.docx_kit`、`kit.docs.md2doc_kit`、`kit.crawl.wx_article_kit`、`kit.crawl.web_article_kit`）不读取任何环境变量。
+> 表中未出现的模块（`kit.crawl.article_models`、`kit.crawl.article_io`、`kit.common_kit`、`kit.docs.docx_kit`、`kit.docs.md2doc_kit`、`kit.license_kit`）不读取任何环境变量。
 
 **基础与日志**（影响 `kit.config` 及所有模块的日志输出）
 
@@ -196,6 +197,21 @@ SQLITE_DB_PATH=./data/sqlite.db
 > `LAYA_HF_*` 同样由 kit 在**导入 laya 之前**经 `os.environ.setdefault` 应用，不覆盖显式配置；
 > `LAYA_MODEL` / `LAYA_DEVICE` 由 `Settings` 读取（进程内缓存，改后需重启进程）。
 
+**DeepSeek Search / Fetch** → `kit.crawl.deepseek_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `DEEPSEEK_API_KEY` | 无 | Search / Fetch 鉴权 Key（与模型对话共用同一套）；缺失时调用抛 `DeepSeekKitError` |
+| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | API 基础地址 |
+| `DEEPSEEK_TIMEOUT` | `60`（1–600） | 单次 HTTP 请求超时（秒） |
+| `DEEPSEEK_MAX_RETRIES` | `2`（0–5） | 408 / 429 / 5xx 重试次数（不含首次请求）；其它 4xx 不重试 |
+
+**文章抓取长度自检** → `kit.crawl.wx_article_kit` / `web_article_kit` / `deepseek_kit`
+
+| 环境变量 | 默认值 | 作用 |
+|----------|--------|------|
+| `CRAWL_MIN_CONTENT_CHARS` | `500`（≥0） | 正文短于该长度时写入 `warnings`（非致命，不改成功语义、不截断正文）；`0` 关闭该判据 |
+
 **云 OCR**（任何 `ocr="hosted"` 的转换）→ `kit.docs.anydoc_kit`
 
 | 环境变量 | 默认值 | 作用 |
@@ -293,9 +309,9 @@ from kit import session_scope, transactional, DBError       # 等价
 | 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
 | 原生表 | `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_touch(table_name, where, params=None) -> int` | 只刷新 `updated_*`（需先 `enable`；表无该列抛 `DBError`） |
+| 原生表 | `raw_delete(table_name, where, params=None) -> int` | 条件删除（`where` 必填） |
+| 原生表 | `build_raw_insert / build_raw_update / build_raw_touch / build_raw_delete` | 只拼装不执行，返回 `(语句, 参数)`，供**自有事务**内 `session.execute(*builder(...))` |
 | 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
 | 事务 | `transaction()` | 事务上下文管理器，`with PgKit.transaction() as session:` |
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
@@ -429,57 +445,9 @@ 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")
 ```
 
-#### 0.2.2 行为变更（升级须知）
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B1 | `search_vectors` 新增 `exact: bool = True`，默认**精确** | SQLite 返回的 `distance` 由量化值（≈L2×255）变为**真值 L2**；需旧口径请显式 `exact=False` |
-| B2 | `filter_sql` 语义统一为**先过滤、再取 top_k** | 传 `filter_sql` 的调用返回值**变多/变全**（旧结果 ⊆ 新结果）；曾自行放大 `top_k` 兜底的调用可收紧 |
-| B3 | 默认 `distance_type` 由 `"COSINE"` 改为 `"L2"` | 依赖默认值的调用方请显式传 `distance_type="COSINE"` |
-| B4 | `create_vector_table` 的 `dims` **必填**，参数顺序为 `(table_name, dims, id_col, column, extra_cols)` | `create_vector_table("t")` 类调用需补维度；位置传 `id_col` 的调用改为关键字 |
-| B5 | MySQL 的 `search_vectors` 异常由 `NotImplementedError` 改为 `VectorNotSupportedError`（继承 `DBError`） | `except NotImplementedError` 需改为 `except VectorNotSupportedError`（或 `except DBError`） |
-
-> 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
-> `insert_vectors` 支持二维 numpy 数组与批量提交。
-
-#### 0.2.6 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| D1 | `prepare_statement` 的 `params` 支持**参数行列表**（`list[dict]`）：**原样返回该列表** → `session.execute(*prepare_statement(sql, params))` 即批量执行（executemany），与 `build_insert_vectors` 的返回形态直接对接；行键集不一致或行值含序列 → 本地可操作 `ValueError`（与 `execute` 批量形态**同一规则**） | 向后兼容：单字典 / `None` 形态行为不变；行列表形态**不做** `IN` 展开（与批量互斥） |
-| D1 | 文档：修正「自有事务」示例——0.2.5 的示例把 `build_insert_vectors` 返回的**行列表**传给了单字典形态，照抄会抛 `AttributeError: 'list' object has no attribute 'items'` | **纯文档缺陷修正**（0.2.5 示例照抄即崩） |
-| — | 文档：批量执行补充 `rowcount` 备注——忽略型写入（如 SQLite `INSERT OR IGNORE`）的冲突行不计入 `rowcount`（即 `rowcount` = 实际插入数；⚠ 仅 SQLite 实测） | 文档 |
-
-#### 0.2.5 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| — | 新增**模块级公共函数** `prepare_statement(sql, params=None) -> (语句, 归一化参数)`：供调用方在**自有事务**内执行原生 SQL（含 `IN :ids`），**调用方无须 import `sqlalchemy`**；与 `query` / `execute` 同一实现（单一事实源） | **纯新增**：`query` / `transaction` 的签名与行为**零变更**；共享方法数仍为 **24**（模块级函数不计入） |
-| — | `execute` 的 `params` 支持**字典列表**（executemany，同一语句 + N 行参数一次往返）；**空列表**不触库返回 `0` | 向后兼容：单字典 / `None` 形态行为不变；批量要求各行字典**键集一致**、行值为**标量**（与 `IN` 展开互斥），违规在本地抛可操作 `ValueError`（含行号），不触库 |
-| — | 文档：自有事务示例改用 `prepare_statement`（不再需要 `from sqlalchemy import text`）；补「批量执行」说明与约束 | 文档 |
-
-> ⚠ `:name::type` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 `text()` 识别**（0.2.5 之前亦如此），
+> ⚠ `:name::type` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 `text()` 识别**，
 > 请改用 `CAST(:name AS type)`。
 
-#### 0.2.4 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B4 | **入参自洽性校验**（`extra_data` 的键）：保留绑定名 `id` / `vec`、与 `id_col` / `column` 重复、不是合法标识符、`id_col == column` → 抛可操作的 `ValueError` | **唯一行为变更**：此前 SQLite 会**静默写坏数据**（如 `id` 列被覆盖）、PG/MySQL 报误导性错误；正常调用**零影响** |
-| — | 新增共享方法 `build_insert_vectors`（只拼装不执行，由 `BaseDbKit` 收敛 → 共享方法 23 → **24**） | 纯新增：可在**自有事务**内写向量行（见下） |
-| — | `create_vector_table` 的 `extra_cols` 支持 `{列名: 类型串}`（与 `create_raw_table` 同形） | 纯新增：既有 `[{"name","type"}]` 形态保留，两者产出 DDL 逐字一致 |
-| — | 后端差异收口：向量列占位符由 `VECTOR_PLACEHOLDER` 驱动（MySQL = `STRING_TO_VECTOR(:vec)`） | 内部整理：公开签名与行为不变 |
-| — | `SQLiteKit.insert_vectors` 的事务获取统一为 `transaction()`（与另两库同构） | 内部一致：行为等价（自成一事务并提交） |
-
-#### 0.2.3 变更
-
-| 编号 | 变更 | 影响 |
-|------|------|------|
-| B6 | **`PgKit.get_table_info` 按数据库解析语义定位表**（`search_path` 解析到的那张表） | 多 schema 下同名表**不再混行**；单 schema / `public` 场景**无影响**；只接受非限定表名 |
-| — | `query` / `execute` 支持**列表参数**（`IN :ids`，三库通用） | 纯新增；`set`/`frozenset` 自动归一化为 `list` |
-| — | 新增 `SQLiteKit.encode_vector` / `decode_vector`（小端 float32） | 纯新增：可在自有事务内写向量表，见下 |
-| — | 导出面统一：`from kit.db import PgKit, MySqlKit, SQLiteKit, build_pg_url, …` | 纯新增；既有导出未删除/未改名 |
-
 **两段查询范式（推荐用法）**：`search_vectors` 只返回 `[{"id", "distance"}]`，载荷二次取回：
 
 ```python
@@ -586,13 +554,15 @@ 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` 自带事务；
+**原生写工具**：`raw_insert` / `raw_update` / `raw_touch` / `raw_delete` 自带事务；
 `build_raw_*` 只拼装（返回 `(语句, 参数)`），供 `with Kit.transaction() as session:` 内使用：
 
 ```python
@@ -865,6 +835,61 @@ CommonKit.format_current_time("yyyy-MM-dd")
 
 ---
 
+## kit.license_kit —— 离线授权签发与校验
+
+零第三方依赖（`cryptography` 已在 base），按需 import。校验链：签名 → 产品 → 机器码 → 有效期。
+
+```python
+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)
+```
+
+| 符号 | 说明 |
+|------|------|
+| `LicenseKit.generate_keypair() -> (str, str)` | 生成 Ed25519（私钥 PEM, 公钥 PEM） |
+| `LicenseKit.get_machine_code() -> str` | 本机机器码（16 位十六进制；⚠ 仅 Windows 平台） |
+| `LicenseKit.export_fingerprint_file(path) -> Path` | 导出机器指纹文件 |
+| `LicenseKit.parse_fingerprint_file(path) -> str` | 从指纹文件读回机器码 |
+| `LicenseKit.sign(payload, private_key_pem) -> str` | 签发授权 token |
+| `LicenseVerifier(public_key_pem, license_path)` | 构造验签器（绑定公钥与 license 文件） |
+| `LicenseVerifier.verify(*, product, machine_code, now=None) -> LicensePayload` | 全量校验并返回载荷；`now=None` 取 aware UTC，naive 按 UTC 解释 |
+| `LicenseVerifier.reverify() -> LicensePayload` | 用最近一次成功 `verify` 的上下文重新校验（文件被换会失败） |
+| `LicenseVerifier.file_signature` | 当前 license 文件的签名（属性） |
+
+`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`）

{sdpy_kit-0.6.0 → sdpy_kit-0.6.2}/kit/__init__.py

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

{sdpy_kit-0.6.0 → sdpy_kit-0.6.2}/kit/db/audit.py

@@ -68,6 +68,7 @@ UPDATE    不参与        空才填                   不参与
     AuditConfig.enable(user_resolver=get_current_userid)  # 应用启动时调用一次
 """
 
+import re
 import threading
 from collections.abc import Callable, Generator, Mapping, MutableMapping
 from contextlib import contextmanager
@@ -132,6 +133,23 @@ def _is_empty(value: object) -> bool:
     return isinstance(value, str) and not value.strip()
 
 
+# 列名会被拼进 SQL 的标识符位置（`SET name = :name` / `INSERT ... (name)`），
+# 故配置入口必须与 raw_* 的 data 键同一套白名单，避免手误到写入时才报晦涩错误。
+_IDENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _check_field_name(name: object) -> None:
+    """校验配置的列名是合法标识符（拼接进 SQL 前拦截）
+
+    Raises:
+        ValueError: 非字符串 / 空串 / 含字母、数字、下划线以外的字符 / 以数字开头
+    """
+    if not isinstance(name, str) or not _IDENT_RE.match(name):
+        raise ValueError(
+            f"{name!r} 不是合法列名（仅允许字母、数字、下划线，且不能以数字开头）"
+        )
+
+
 def _is_string_type(column_type: TypeEngine[Any]) -> bool:
     """是否为字符串列（兼容 SQLModel 的 ``AutoString`` 这类 ``TypeDecorator``）
 
@@ -238,7 +256,8 @@ class AuditConfig:
                 ``deleted``
 
         Raises:
-            ValueError: 出现未知槽位（防手误，例如把 ``created_at`` 写成 ``create_at``）
+            ValueError: 出现未知槽位（防手误，例如把 ``created_at`` 写成 ``create_at``）；
+                或列名不是合法标识符（会被拼进 SQL 的标识符位置）
 
         用法::
 
@@ -254,6 +273,8 @@ class AuditConfig:
                     f"未知的字段槽位: {sorted(unknown)}；"
                     f"可用槽位: {sorted(DEFAULT_FIELDS)}"
                 )
+            for name in fields.values():
+                _check_field_name(name)
             merged.update(fields)
         with cls._lock:
             cls._fields = merged
@@ -365,6 +386,14 @@ def _candidates(slot: str) -> tuple[str, ...]:
     return (primary, *(alias for alias in aliases if alias != primary))
 
 
+def candidate_columns(slot: str) -> tuple[str, ...]:
+    """槽位的候选列名（当前配置名 + 内置别名），供错误消息与诊断使用
+
+    ⚠ 内部符号（不进 ``kit.db.__all__``）。
+    """
+    return _candidates(slot)
+
+
 def insert_only_columns() -> tuple[str, ...]:
     """只在 INSERT 填充的列（created_at / created_by 槽位的**全部候选**）
 

{sdpy_kit-0.6.0 → sdpy_kit-0.6.2}/kit/db/base_db_kit.py

@@ -58,7 +58,9 @@ from sqlmodel import Session, SQLModel
 from kit.common_kit import CommonKit
 from kit.config.log_config import get_default_logger
 from kit.db.audit import (
+    UPDATED_AT,
     AuditConfig,
+    candidate_columns,
     deleted_predicate,
     fill_insert_for,
     fill_update,
@@ -195,7 +197,15 @@ def _adapt_write_values(
             data[name] = json.dumps(value, ensure_ascii=False)
             continue
         if isinstance(value, _WRITE_SEQUENCE_TYPES):
-            if isinstance(columns.get(name), JSON):
+            column_type = columns.get(name)
+            if column_type is None:
+                raise ValueError(
+                    f"{name!r} 的值是序列，但表 {table_name} 中查不到该列"
+                    f"（或列探测失败）：请确认表已提交建好；"
+                    f"JSON 列请传 dict / list；向量请用 to_vector_literal(...)；"
+                    f"数组等其它类型请用 execute() 手写 SQL"
+                )
+            if isinstance(column_type, JSON):
                 data[name] = json.dumps(list(value), ensure_ascii=False)
             else:
                 raise ValueError(
@@ -1000,8 +1010,9 @@ class BaseDbKit(ABC):
                 "或改用 raw_update 显式给字段"
             )
         if not touch_columns(cls.DB_TYPE, table_name):
+            expected = " / ".join(candidate_columns(UPDATED_AT))
             raise DBError(
-                f"表 {table_name} 没有 updated_at 相关列，无法 touch；"
+                f"表 {table_name} 没有 {expected} 中的任何一列，无法 touch；"
                 f"请改用 raw_update 显式给字段"
             )