sdpy-kit 0.2.0__tar.gz → 0.2.1__tar.gz

{sdpy_kit-0.2.0 → sdpy_kit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.0
+Version: 0.2.1
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -84,7 +84,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | 模块 | 类 / 入口 | 能力 | 需要 extra |
 |------|-----------|------|-----------|
 | `kit.config` | `get_settings` / `get_default_logger` | 配置单例与统一日志 | 无 |
-| `kit.db` | `SQLiteKit` / `PgKit` / `MySqlKit` / `CRUDBase` | 统一 CRUD、原生 SQL、事务、表管理 | `pg` / `mysql` / `sqliteai` |
+| `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` |
@@ -110,8 +110,8 @@ uv add sdpy-kit
 
 | extra | 能力 | 安装 |
 |-------|------|------|
-| `pg` | PgKit（PostgreSQL 驱动） | `pip install "sdpy-kit[pg]"` |
-| `mysql` | MySqlKit（MySQL 驱动） | `pip install "sdpy-kit[mysql]"` |
+| `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]"` |
@@ -336,7 +336,7 @@ from kit.db import session_scope, transactional, DBError    # 推荐
 from kit import session_scope, transactional, DBError       # 等价
 ```
 
-### 1. 三个数据库 Kit（API 完全一致）
+### 1. 三个数据库 Kit（23 个共享方法 API 完全一致）
 
 | 类 | 导入 | 数据库 | extra |
 |----|------|--------|-------|
@@ -344,13 +344,14 @@ 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` |
 
-**共有方法（19 个，全部为 classmethod，内部自动提交）**
+**共有方法（23 个，全部为 classmethod，内部自动提交）**
 
 | 分组 | 方法 | 说明 |
 |------|------|------|
 | 连接 | `connect() -> bool` | 建引擎并验证连通 |
 | 连接 | `close() -> None` | 关闭引擎 |
 | 连接 | `is_connected() -> bool` | 探测当前是否可连 |
+| 连接 | `raw_connection()` | 取原生 DBAPI 连接（PG=psycopg2 / MySQL=pymysql / SQLite=sqlite3）；调用方负责 commit 与 close，psycopg2 / pymysql 默认不自动提交 |
 | ORM | `create(model, data) -> Model` | 插入单条 |
 | ORM | `create_multi(model, data_list) -> list[Model]` | 批量插入 |
 | ORM | `get(model, id) -> Model \| None` | 按主键查询 |
@@ -362,6 +363,9 @@ from kit import session_scope, transactional, DBError       # 等价
 | ORM | `count(model) -> int` | 记录总数 |
 | 原生 SQL | `query(sql, params=None) -> list[dict]` | 原生查询，返回字典列表 |
 | 原生 SQL | `execute(sql, params=None) -> int` | 原生写入，返回影响行数 |
+| 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
+| 原生表 | `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
+| 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
 | 事务 | `transaction()` | 事务上下文管理器，`with PgKit.transaction() as session:` |
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
 | 表 | `table_exists(table_name) -> bool` | 判断表是否存在 |
@@ -369,11 +373,15 @@ from kit import session_scope, transactional, DBError       # 等价
 | 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（三个 Kit 各自实现） |
 
 ```python
+from sqlalchemy import BigInteger
 from sqlmodel import SQLModel, Field
+from kit.common_kit import CommonKit
 from kit.db.sqlite_kit import SQLiteKit
 
 class User(SQLModel, table=True):
-    id: int | None = Field(default=None, primary_key=True)
+    # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
+    id: int = Field(default_factory=CommonKit.generate_snowflake_id,
+                    primary_key=True, sa_type=BigInteger)
     name: str
 
 SQLiteKit.connect()
@@ -392,31 +400,60 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 ```
 
 > 切换数据库：把 import 的 `SQLiteKit` 换成 `PgKit` / `MySqlKit` 即可，其余代码不变。
+> 注意两点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
+> **三库同名同参但能力不同**，尤其 **MySQL 侧检索不可用**（见下）。
 
-### 2. SQLiteKit 独有方法
-
-无需额外依赖：
-
-| 方法 | 说明 |
-|------|------|
-| `raw_connection()` | 取原生 DBAPI 连接（sqlite-vector 扩展已自动加载），调用方负责关闭 |
-| `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表 |
-| `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
-| `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
+### 2. 向量方法（三库同名同参，能力差异化）
 
-向量方法（需 `pip install "sdpy-kit[sqliteai]"`）：
+> 签名在 `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`。
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, id_col="id", dims=384, extra_cols=None) -> None` | 建含向量列的表 |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None) -> int` | 批量插入向量 |
-| `search_vectors(table_name, query_vector, top_k=10, distance_type="COSINE", filter_sql=None) -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance", ...}` |
-| `vector_version() -> str` | 向量扩展版本，不可用时返回 `"unavailable"` |
+| `create_vector_table(table_name, id_col="id", dims=384, extra_cols=None) -> None` | 建含向量列的表（PG / MySQL 侧 `dims` 有约束） |
+| `insert_vectors(table_name, vectors, ids=None, extra_data=None) -> int` | 批量插入向量（单事务提交）；`ids=None` 时由 Kit 生成雪花 ID |
+| `search_vectors(table_name, query_vector, top_k=10, distance_type="COSINE", filter_sql=None) -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance"}`；**MySQL 侧抛 `NotImplementedError`** |
+| `vector_version() -> str` | 向量后端版本；不可用时返回 `"unavailable"`（MySQL 侧为服务端版本号） |
+
+**能力差异（跨库不可比较 `distance` 数值）**：
+
+| 项 | `SQLiteKit`（sqlite-vector） | `PgKit`（pgvector） | `MySqlKit`（9.x 原生） |
+|----|------------------------------|---------------------|------------------------|
+| 支持的 `distance_type` | **仅 L2**（该形参当前不生效，取任何值结果相同） | `COSINE` / `L2` / `L1` / `DOT`（负内积） / `SQUARED_L2` | **无（检索不可用）** |
+| 非法取值 | 忽略 | 抛 `ValueError` | `search_vectors` 一律抛 `NotImplementedError` |
+| `distance` 口径 | int8 量化整数距离（= L2 × 255，非物理距离） | 真实距离 | — |
+| 维度约束 | 无 | 强制（不匹配即报错） | 上限约束（超限报错） |
+| `filter_sql` 与 `top_k` | **先取 top_k 再过滤**（可能少于 top_k） | **先过滤再取 top_k** | 不适用 |
+| 索引 | 每次检索 `vector_init` + `vector_quantize` | 默认无索引（可自建 hnsw/ivfflat） | 无法建（B-Tree 拒绝向量列） |
+
+> MySQL `DISTANCE()` / `VECTOR_DISTANCE()` 仅 HeatWave on OCI 与 MySQL AI 提供
+> （Community 实测报 `1305 FUNCTION ... does not exist`）；故 `MySqlKit` 只覆盖存储侧。
+
+**主键与 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)` 会重复）。
 
 ```python
+# SQLite
+from kit.db.sqlite_kit import SQLiteKit
 SQLiteKit.create_vector_table("images", dims=384)
 SQLiteKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5)
+
+# PostgreSQL（签名相同；可选 COSINE/L2/L1/DOT/SQUARED_L2）
+from kit.db.pg_kit import PgKit
+PgKit.create_vector_table("images", dims=384)
+PgKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
+rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="L2")
+
+# MySQL（仅存储；search_vectors 会抛 NotImplementedError）
+from kit.db.mysql_kit import MySqlKit
+MySqlKit.create_vector_table("images", dims=384)
+MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 ```
 
 ### 3. CRUDBase（配合 session_scope，不自动提交）
@@ -481,10 +518,16 @@ def transfer(session: Session, from_id: int, to_id: int, amount: float) -> None:
 ### 5. 模型混入类与查询构建器
 
 ```python
+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, table=True):
-    id: int | None = Field(default=None, primary_key=True)
+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
 ```
 

{sdpy_kit-0.2.0 → sdpy_kit-0.2.1}/README.md

@@ -14,7 +14,7 @@ SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
 | 模块 | 类 / 入口 | 能力 | 需要 extra |
 |------|-----------|------|-----------|
 | `kit.config` | `get_settings` / `get_default_logger` | 配置单例与统一日志 | 无 |
-| `kit.db` | `SQLiteKit` / `PgKit` / `MySqlKit` / `CRUDBase` | 统一 CRUD、原生 SQL、事务、表管理 | `pg` / `mysql` / `sqliteai` |
+| `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` |
@@ -40,8 +40,8 @@ uv add sdpy-kit
 
 | extra | 能力 | 安装 |
 |-------|------|------|
-| `pg` | PgKit（PostgreSQL 驱动） | `pip install "sdpy-kit[pg]"` |
-| `mysql` | MySqlKit（MySQL 驱动） | `pip install "sdpy-kit[mysql]"` |
+| `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]"` |
@@ -266,7 +266,7 @@ from kit.db import session_scope, transactional, DBError    # 推荐
 from kit import session_scope, transactional, DBError       # 等价
 ```
 
-### 1. 三个数据库 Kit（API 完全一致）
+### 1. 三个数据库 Kit（23 个共享方法 API 完全一致）
 
 | 类 | 导入 | 数据库 | extra |
 |----|------|--------|-------|
@@ -274,13 +274,14 @@ 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` |
 
-**共有方法（19 个，全部为 classmethod，内部自动提交）**
+**共有方法（23 个，全部为 classmethod，内部自动提交）**
 
 | 分组 | 方法 | 说明 |
 |------|------|------|
 | 连接 | `connect() -> bool` | 建引擎并验证连通 |
 | 连接 | `close() -> None` | 关闭引擎 |
 | 连接 | `is_connected() -> bool` | 探测当前是否可连 |
+| 连接 | `raw_connection()` | 取原生 DBAPI 连接（PG=psycopg2 / MySQL=pymysql / SQLite=sqlite3）；调用方负责 commit 与 close，psycopg2 / pymysql 默认不自动提交 |
 | ORM | `create(model, data) -> Model` | 插入单条 |
 | ORM | `create_multi(model, data_list) -> list[Model]` | 批量插入 |
 | ORM | `get(model, id) -> Model \| None` | 按主键查询 |
@@ -292,6 +293,9 @@ from kit import session_scope, transactional, DBError       # 等价
 | ORM | `count(model) -> int` | 记录总数 |
 | 原生 SQL | `query(sql, params=None) -> list[dict]` | 原生查询，返回字典列表 |
 | 原生 SQL | `execute(sql, params=None) -> int` | 原生写入，返回影响行数 |
+| 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
+| 原生表 | `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
+| 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
 | 事务 | `transaction()` | 事务上下文管理器，`with PgKit.transaction() as session:` |
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
 | 表 | `table_exists(table_name) -> bool` | 判断表是否存在 |
@@ -299,11 +303,15 @@ from kit import session_scope, transactional, DBError       # 等价
 | 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（三个 Kit 各自实现） |
 
 ```python
+from sqlalchemy import BigInteger
 from sqlmodel import SQLModel, Field
+from kit.common_kit import CommonKit
 from kit.db.sqlite_kit import SQLiteKit
 
 class User(SQLModel, table=True):
-    id: int | None = Field(default=None, primary_key=True)
+    # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
+    id: int = Field(default_factory=CommonKit.generate_snowflake_id,
+                    primary_key=True, sa_type=BigInteger)
     name: str
 
 SQLiteKit.connect()
@@ -322,31 +330,60 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 ```
 
 > 切换数据库：把 import 的 `SQLiteKit` 换成 `PgKit` / `MySqlKit` 即可，其余代码不变。
+> 注意两点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
+> **三库同名同参但能力不同**，尤其 **MySQL 侧检索不可用**（见下）。
 
-### 2. SQLiteKit 独有方法
-
-无需额外依赖：
-
-| 方法 | 说明 |
-|------|------|
-| `raw_connection()` | 取原生 DBAPI 连接（sqlite-vector 扩展已自动加载），调用方负责关闭 |
-| `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表 |
-| `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
-| `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
+### 2. 向量方法（三库同名同参，能力差异化）
 
-向量方法（需 `pip install "sdpy-kit[sqliteai]"`）：
+> 签名在 `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`。
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, id_col="id", dims=384, extra_cols=None) -> None` | 建含向量列的表 |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None) -> int` | 批量插入向量 |
-| `search_vectors(table_name, query_vector, top_k=10, distance_type="COSINE", filter_sql=None) -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance", ...}` |
-| `vector_version() -> str` | 向量扩展版本，不可用时返回 `"unavailable"` |
+| `create_vector_table(table_name, id_col="id", dims=384, extra_cols=None) -> None` | 建含向量列的表（PG / MySQL 侧 `dims` 有约束） |
+| `insert_vectors(table_name, vectors, ids=None, extra_data=None) -> int` | 批量插入向量（单事务提交）；`ids=None` 时由 Kit 生成雪花 ID |
+| `search_vectors(table_name, query_vector, top_k=10, distance_type="COSINE", filter_sql=None) -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance"}`；**MySQL 侧抛 `NotImplementedError`** |
+| `vector_version() -> str` | 向量后端版本；不可用时返回 `"unavailable"`（MySQL 侧为服务端版本号） |
+
+**能力差异（跨库不可比较 `distance` 数值）**：
+
+| 项 | `SQLiteKit`（sqlite-vector） | `PgKit`（pgvector） | `MySqlKit`（9.x 原生） |
+|----|------------------------------|---------------------|------------------------|
+| 支持的 `distance_type` | **仅 L2**（该形参当前不生效，取任何值结果相同） | `COSINE` / `L2` / `L1` / `DOT`（负内积） / `SQUARED_L2` | **无（检索不可用）** |
+| 非法取值 | 忽略 | 抛 `ValueError` | `search_vectors` 一律抛 `NotImplementedError` |
+| `distance` 口径 | int8 量化整数距离（= L2 × 255，非物理距离） | 真实距离 | — |
+| 维度约束 | 无 | 强制（不匹配即报错） | 上限约束（超限报错） |
+| `filter_sql` 与 `top_k` | **先取 top_k 再过滤**（可能少于 top_k） | **先过滤再取 top_k** | 不适用 |
+| 索引 | 每次检索 `vector_init` + `vector_quantize` | 默认无索引（可自建 hnsw/ivfflat） | 无法建（B-Tree 拒绝向量列） |
+
+> MySQL `DISTANCE()` / `VECTOR_DISTANCE()` 仅 HeatWave on OCI 与 MySQL AI 提供
+> （Community 实测报 `1305 FUNCTION ... does not exist`）；故 `MySqlKit` 只覆盖存储侧。
+
+**主键与 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)` 会重复）。
 
 ```python
+# SQLite
+from kit.db.sqlite_kit import SQLiteKit
 SQLiteKit.create_vector_table("images", dims=384)
 SQLiteKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5)
+
+# PostgreSQL（签名相同；可选 COSINE/L2/L1/DOT/SQUARED_L2）
+from kit.db.pg_kit import PgKit
+PgKit.create_vector_table("images", dims=384)
+PgKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
+rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="L2")
+
+# MySQL（仅存储；search_vectors 会抛 NotImplementedError）
+from kit.db.mysql_kit import MySqlKit
+MySqlKit.create_vector_table("images", dims=384)
+MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 ```
 
 ### 3. CRUDBase（配合 session_scope，不自动提交）
@@ -411,10 +448,16 @@ def transfer(session: Session, from_id: int, to_id: int, amount: float) -> None:
 ### 5. 模型混入类与查询构建器
 
 ```python
+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, table=True):
-    id: int | None = Field(default=None, primary_key=True)
+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
 ```
 

{sdpy_kit-0.2.0 → sdpy_kit-0.2.1}/kit/__init__.py

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

{sdpy_kit-0.2.0 → sdpy_kit-0.2.1}/kit/db/base_db_kit.py

@@ -23,9 +23,13 @@ from __future__ import annotations
 """数据库 Kit 共享基类（DRY 收敛）
 
 三个数据库 Kit（PgKit / MySqlKit / SQLiteKit）在重构前拥有约 400 行几乎
-逐行相同的代码（连接管理 / ORM / 原生 SQL / 事务 / 表操作），仅 DB_TYPE
-与 get_table_info 的 SQL 不同。本基类将全部共享实现收敛，子类只声明
-DB_TYPE 并覆写 get_table_info（SQLite 另含向量操作）。
+逐行相同的代码（连接管理 / ORM / 原生 SQL / 原生表操作 / 事务 / 表操作），
+仅 DB_TYPE 与 get_table_info 的 SQL 不同。本基类将全部共享实现收敛，子类
+只声明 DB_TYPE 并覆写 get_table_info（SQLite 另含向量操作）。
+
+2026-10-11：将原本仅 SQLiteKit 具备的 4 个方言无关方法（raw_connection /
+create_raw_table / raw_insert / raw_get_by）上移到本基类，使三个 Kit 在该层
+的能力与签名完全一致（共享方法 19 → 23）。
 
 设计要点：
 - 所有公开方法保留原签名与语义，外部调用零影响。
@@ -46,8 +50,10 @@ from contextlib import contextmanager
 from typing import cast
 
 from sqlalchemy import text
+from sqlalchemy.pool import PoolProxiedConnection
 from sqlmodel import Session, SQLModel
 
+from kit.common_kit import CommonKit
 from kit.config.log_config import get_default_logger
 from kit.db.crud import CRUDBase
 from kit.db.engine import (
@@ -83,6 +89,27 @@ def _get_crud[T: SQLModel](model: type[T]) -> CRUDBase[T, T, T]:
     return cast(CRUDBase[T, T, T], crud)
 
 
+def to_vector_literal(vector: builtins.list[float]) -> str:
+    """把 float 列表转换为向量文本字面量（如 [0.1, 0.2] → "[0.1,0.2]"）
+
+    供共享相同文本格式的数据库后端复用：PgKit（pgvector 的 vector 类型）与
+    MySqlKit（STRING_TO_VECTOR）。SQLiteKit 走 float32 bytes，不使用本函数。
+    """
+    return "[" + ",".join(repr(float(value)) for value in vector) + "]"
+
+
+def generate_snowflake_ids(count: int) -> builtins.list[int]:
+    """生成 count 个雪花 ID（int64；当前 18 位，上限 19 位）
+
+    供三个数据库 Kit 的向量方法在调用方未提供 id（``ids=None``）时兜底使用：
+    id 由**应用侧（kit）生成**而非数据库自增，保证三库语义一致，同时避免
+    PostgreSQL 序列不随显式 id 推进的问题（BIGSERIAL → 纯 BIGINT 主键）。
+
+    ⚠ 雪花 ID 超过 2^53，经 JSON 传给 JavaScript 会丢精度，需按字符串传输。
+    """
+    return [CommonKit.generate_snowflake_id() for _ in range(count)]
+
+
 class BaseDbKit(ABC):
     """数据库工具类共享基类
 
@@ -129,6 +156,19 @@ class BaseDbKit(ABC):
         except Exception:
             return False
 
+    @classmethod
+    def raw_connection(cls) -> PoolProxiedConnection:
+        """获取原生 DBAPI 连接（引擎侧扩展加载已由 engine.py 自动完成）
+
+        PostgreSQL 返回 psycopg2 连接、MySQL 返回 pymysql 连接、SQLite 返回
+        sqlite3 连接（sqlite-vector 扩展已自动加载）。用于执行驱动特有函数与
+        静态 DDL。
+
+        ⚠ 调用方负责提交与关闭连接。psycopg2 / pymysql 默认**不开启自动提交**，
+        与 sqlite3 的使用习惯不同：需要落库时必须显式 commit。
+        """
+        return get_engine(cls.DB_TYPE).raw_connection()
+
     # ==================== ORM 操作（自动管理 session） ====================
 
     @classmethod
@@ -350,6 +390,71 @@ class BaseDbKit(ABC):
             logger.info(f"✅ 执行更新 → 影响 {affected} 行")
             return affected
 
+    # ==================== 原生表操作 ====================
+
+    @classmethod
+    def create_raw_table(
+        cls, table_name: str, columns: dict[str, str], if_not_exists: bool = True
+    ) -> None:
+        """根据「列名 → 列定义」字典创建普通表
+
+        Args:
+            table_name: 表名
+            columns: 列定义字典，如 {"id": "BIGSERIAL PRIMARY KEY", "name": "TEXT"}
+            if_not_exists: 是否附加 IF NOT EXISTS（默认 True）
+
+        ⚠ 列定义须按**目标数据库方言**书写，本方法只做字符串拼接与执行，
+        不做方言翻译：
+            PostgreSQL: {"id": "BIGSERIAL PRIMARY KEY", "name": "TEXT"}
+            MySQL:      {"id": "INT AUTO_INCREMENT PRIMARY KEY", "name": "VARCHAR(100)"}
+            SQLite:     {"id": "INTEGER PRIMARY KEY", "name": "TEXT"}
+        """
+        column_defs = ", ".join(
+            f"{name} {definition}" for name, definition in columns.items()
+        )
+        if_not_exists_sql = "IF NOT EXISTS " if if_not_exists else ""
+        sql = f"CREATE TABLE {if_not_exists_sql}{table_name} ({column_defs})"
+        with get_engine(cls.DB_TYPE).connect() as conn:
+            conn.execute(text(sql))
+            conn.commit()
+        logger.info(f"✅ 创建表 {table_name}")
+
+    @classmethod
+    def raw_insert(cls, table_name: str, data: dict[str, object]) -> int:
+        """向指定表插入一行数据（键为列名）
+
+        Args:
+            table_name: 表名
+            data: 列名 → 值 字典
+
+        Returns:
+            受影响的行数
+        """
+        columns = ", ".join(data.keys())
+        placeholders = ", ".join(f":{name}" for name in data)
+        sql = f"INSERT INTO {table_name} ({columns}) VALUES ({placeholders})"
+        return cls.execute(sql, dict(data))
+
+    @classmethod
+    def raw_get_by(
+        cls, table_name: str, column: str, value: object
+    ) -> dict[str, object] | None:
+        """按单列等值查询一行
+
+        Args:
+            table_name: 表名
+            column: 列名
+            value: 查询值
+
+        Returns:
+            匹配的第一行（字典）；无匹配返回 None
+        """
+        rows = cls.query(
+            f"SELECT * FROM {table_name} WHERE {column} = :value LIMIT 1",
+            {"value": value},
+        )
+        return rows[0] if rows else None
+
     # ==================== 事务管理 ====================
 
     @classmethod