sqlseed 0.1.10__tar.gz → 0.1.12__tar.gz

{sqlseed-0.1.10 → sqlseed-0.1.12}/.gitignore

@@ -35,6 +35,7 @@ ENV/
 # Testing
 .pytest_cache/
 .coverage
+coverage.xml
 htmlcov/
 
 # Type checking
@@ -54,9 +55,6 @@ snapshots/
 # AI cache
 .sqlseed_cache/
 
-# Archived temp files
-_archived_temp/
-
 # macOS
 .DS_Store
 
@@ -67,3 +65,6 @@ _archived_temp/
 dist/
 *.whl
 *.tar.gz
+
+# Local git worktrees
+.worktrees/

{sqlseed-0.1.10 → sqlseed-0.1.12}/CHANGELOG.md

@@ -17,7 +17,7 @@
 - `DataProvider` Protocol，含 `BaseProvider`、`FakerProvider`、`MimesisProvider`
 - `DataStream` 流式数据生成器，内存高效的批量处理
 - `RelationResolver` 外键依赖拓扑排序
-- 基于 `pluggy` 的插件系统，10 个 Hook 点
+- 基于 `pluggy` 的插件系统，11 个 Hook 点
 - CLI 命令：`fill`、`preview`、`inspect`、`init`、`replay`、`ai-suggest`
 - Python API：`sqlseed.fill()`、`sqlseed.connect()`、`sqlseed.fill_from_config()`、`sqlseed.preview()`
 - YAML/JSON 配置文件支持
@@ -41,7 +41,7 @@
 - `AIConfig` 可配置模型、API Key 和 Base URL
 - 默认模型：`qwen3-coder-plus`，支持环境变量覆盖
 - CLI `ai-suggest` 命令，AI 驱动的 YAML 生成
-- 自然语言配置（`nl_config.py`）
+- 自然语言配置（`nl_config.py`，已移除，功能由 `SchemaAnalyzer` + `AiConfigRefiner` 替代）
 
 #### AI Evolution — 智能增强
 - 结构化输出迁移：YAML → JSON，`response_format` 强制 JSON 输出
@@ -78,3 +78,9 @@
 - 表达式引擎增加超时保护（默认 5 秒），防止无限循环
 - 解决 `random.seed()` 类型异常（`rstr` 集成于流式生成器）
 - `fill_from_config` 中 transform 属性正确传递到内部编排器
+- `ProviderRegistry.register_from_entry_points()` 修正 provider 类与普通插件入口点的区分逻辑，非 provider 入口点（如 `sqlseed_ai:plugin`）不再产生误报 warning
+
+### 变更
+- README / 开发文档与当前实现对齐：MCP tool 名称、Provider 协议示例、`sqlseed_shared_pool_loaded` 触发时机与 `UnknownGeneratorError` 行为说明已同步
+- 移除 `suggest.py`（`ColumnSuggester`）和 `nl_config.py`（`NLConfigGenerator`），其功能由 `SchemaAnalyzer` + `AiConfigRefiner` 完全替代。如有外部代码直接 `from sqlseed_ai.suggest import ColumnSuggester` 或 `from sqlseed_ai.nl_config import NLConfigGenerator`，将产生 `ImportError`
+- `plugins/sqlseed-ai/README.md` 功能描述与当前实际入口对齐，移除未对外提供的 "Column-level Suggestions" / "Natural Language Config" 描述

{sqlseed-0.1.10 → sqlseed-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlseed
-Version: 0.1.10
+Version: 0.1.12
 Summary: Declarative SQLite test data generation toolkit
 Project-URL: Homepage, https://github.com/sunbos/sqlseed
 Project-URL: Documentation, https://github.com/sunbos/sqlseed#readme
@@ -38,6 +38,7 @@ Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pre-commit>=3.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
@@ -56,17 +57,17 @@ Description-Content-Type: text/markdown
 
 ### 声明式 SQLite 测试数据生成工具包
 
-**一行代码，十万行数据。零配置智能生成，AI 驱动精准调优。**
+**一行代码，数万行数据。零配置智能生成，AI 驱动精准调优。**
 
 [![CI](https://github.com/sunbos/sqlseed/actions/workflows/ci.yml/badge.svg)](https://github.com/sunbos/sqlseed/actions)
-[![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776ab.svg?logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-3776ab.svg?logo=python\&logoColor=white)](https://www.python.org/downloads/)
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![Type: mypy](https://img.shields.io/badge/type%20checker-mypy-blue.svg)](https://mypy-lang.org/)
 
 </div>
 
----
+***
 
 ```python
 import sqlseed
@@ -77,21 +78,21 @@ print(result)
 # → GenerationResult(table=users, count=100000, elapsed=2.34s, speed=42735 rows/s)
 ```
 
----
+***
 
 ## 💡 为什么选择 sqlseed？
 
 在开发和测试流程中，我们经常需要为 SQLite 数据库填充大量真实感的测试数据。传统方式要么手写冗长的数据生成脚本，要么使用难以维护的 SQL fixtures。sqlseed 用一种全新的声明式方式解决了这个问题：
 
-| 特性 | sqlseed | 手写脚本 | SQL Fixtures |
-|:---|:---:|:---:|:---:|
-| 零配置智能生成 | ✅ | ❌ | ❌ |
-| 外键自动维护 | ✅ | 手动 | 手动 |
-| 10 万行 + 数据 | ✅ 流式 | ⚠️ OOM | ❌ |
-| 列语义推断 | ✅ 8 级策略 | ❌ | ❌ |
-| 可重复生成 | ✅ seed | ⚠️ 手动 | ✅ |
-| AI 智能调优 | ✅ LLM | ❌ | ❌ |
-| 配置热重用 | ✅ YAML | ❌ | ❌ |
+| 特性         | sqlseed |  手写脚本  | SQL Fixtures |
+| :--------- | :-----: | :----: | :----------: |
+| 零配置智能生成    |    ✅    |    ❌   |       ❌      |
+| 外键自动维护     |    ✅    |   手动   |      手动      |
+| 10 万行 + 数据 |   ✅ 流式  | ⚠️ OOM |       ❌      |
+| 列语义推断      | ✅ 9 级策略 |    ❌   |       ❌      |
+| 可重复生成      |  ✅ seed |  ⚠️ 手动 |       ✅      |
+| AI 智能调优    |  ✅ LLM  |    ❌   |       ❌      |
+| 配置热重用      |  ✅ YAML |    ❌   |       ❌      |
 
 ## ✨ 核心特性
 
@@ -101,7 +102,7 @@ print(result)
 
 **🚀 零配置智能生成**
 
-自动推断数据库 Schema，通过 8 级策略链为每列选择最佳生成器。列名是 `email`？生成邮箱。列名是 `*_at`？生成时间戳。完全不需要配置。
+自动推断数据库 Schema，通过 9 级策略链为每列选择最佳生成器。列名是 `email`？生成邮箱。列名是 `*_at`？生成时间戳。完全不需要配置。
 
 </td>
 <td width="50%">
@@ -162,7 +163,7 @@ print(result)
 </tr>
 </table>
 
----
+***
 
 ## 📦 安装
 
@@ -217,7 +218,7 @@ mypy src/sqlseed/
 
 </details>
 
----
+***
 
 ## 🚀 快速开始
 
@@ -249,18 +250,19 @@ print(result)
 ```
 
 sqlseed 会自动：
+
 - ✅ 跳过 `id`（自增主键）
 - ✅ 跳过 `is_active`（有默认值）
 - ✅ `name` → 生成真实姓名
 - ✅ `email` → 生成邮箱地址
-- ✅ `age` → 生成 18~100 的整数
+- ✅ `age` → 生成 18\~100 的整数
 - ✅ `phone` → 生成电话号码
 - ✅ `created_at` → 生成日期时间（匹配 `*_at` 模式）
 - ✅ `balance` → 生成浮点数
 
 **完全零配置，智能推断一切。**
 
----
+***
 
 ## 📖 使用教程
 
@@ -298,36 +300,36 @@ print(result)
 
 #### 支持的生成器类型
 
-| 生成器 | 说明 | 参数示例 |
-|:---|:---|:---|
-| `string` | 随机字符串 | `min_length`, `max_length`, `charset` |
-| `integer` | 整数 | `min_value`, `max_value` |
-| `float` | 浮点数 | `min_value`, `max_value`, `precision` |
-| `boolean` | 布尔值 | — |
-| `name` | 人名 | — |
-| `first_name` | 名 | — |
-| `last_name` | 姓 | — |
-| `email` | 邮箱 | — |
-| `phone` | 电话 | — |
-| `address` | 地址 | — |
-| `company` | 公司名 | — |
-| `url` | URL | — |
-| `ipv4` | IPv4 地址 | — |
-| `uuid` | UUID | — |
-| `date` | 日期 | `start_year`, `end_year` |
-| `datetime` | 日期时间 | `start_year`, `end_year` |
-| `timestamp` | Unix 时间戳 | — |
-| `text` | 长文本 | `min_length`, `max_length` |
-| `sentence` | 句子 | — |
-| `password` | 密码 | `length` |
-| `choice` | 从列表选择 | `choices` |
-| `json` | JSON 字符串 | `schema` |
-| `pattern` | 正则匹配 | `regex` |
-| `bytes` | 二进制数据 | `length` |
-| `foreign_key` | 外键引用 | `ref_table`, `ref_column`, `strategy` |
-| `skip` | 跳过（使用默认值/NULL）| — |
-
----
+| 生成器           | 说明             | 参数示例                                  |
+| :------------ | :------------- | :------------------------------------ |
+| `string`      | 随机字符串          | `min_length`, `max_length`, `charset` |
+| `integer`     | 整数             | `min_value`, `max_value`              |
+| `float`       | 浮点数            | `min_value`, `max_value`, `precision` |
+| `boolean`     | 布尔值            | —                                     |
+| `name`        | 人名             | —                                     |
+| `first_name`  | 名              | —                                     |
+| `last_name`   | 姓              | —                                     |
+| `email`       | 邮箱             | —                                     |
+| `phone`       | 电话             | —                                     |
+| `address`     | 地址             | —                                     |
+| `company`     | 公司名            | —                                     |
+| `url`         | URL            | —                                     |
+| `ipv4`        | IPv4 地址        | —                                     |
+| `uuid`        | UUID           | —                                     |
+| `date`        | 日期             | `start_year`, `end_year`              |
+| `datetime`    | 日期时间           | `start_year`, `end_year`              |
+| `timestamp`   | Unix 时间戳       | —                                     |
+| `text`        | 长文本            | `min_length`, `max_length`            |
+| `sentence`    | 句子             | —                                     |
+| `password`    | 密码             | `length`                              |
+| `choice`      | 从列表选择          | `choices`                             |
+| `json`        | JSON 字符串       | `schema`                              |
+| `pattern`     | 正则匹配           | `regex`                               |
+| `bytes`       | 二进制数据          | `length`                              |
+| `foreign_key` | 外键引用           | `ref_table`, `ref_column`, `strategy` |
+| `skip`        | 跳过（使用默认值/NULL） | —                                     |
+
+***
 
 ### 教程 2：多表关联 — 自动维持外键完整性
 
@@ -358,7 +360,7 @@ with sqlseed.connect("app.db", provider="mimesis", locale="zh_CN") as db:
 
 > **💡 提示**：如果两张表之间有同名列（如 `account_id`），即使没有声明外键约束，sqlseed 也会通过 **SharedPool 隐式关联机制**自动维持跨表一致性。
 
----
+***
 
 ### 教程 3：YAML 配置文件驱动批量生成
 
@@ -438,7 +440,7 @@ for r in results:
     print(r)
 ```
 
----
+***
 
 ### 教程 4：派生列与表达式引擎
 
@@ -476,6 +478,7 @@ tables:
 ```
 
 **运作原理**：
+
 1. sqlseed 构建列依赖 DAG：`card_number → last_eight, last_six`
 2. 拓扑排序确定生成顺序
 3. 先生成 `card_number`，再通过表达式 `value[-8:]` 计算 `last_eight`
@@ -483,26 +486,26 @@ tables:
 
 #### 表达式引擎支持的函数
 
-| 函数 | 用法 | 说明 |
-|:---|:---|:---|
-| `upper(s)` | `upper(value)` | 转大写 |
-| `lower(s)` | `lower(value)` | 转小写 |
-| `len(s)` | `len(value)` | 获取长度 |
-| `substr(s, start, end)` | `substr(value, 0, 8)` | 子串 |
-| `concat(*args)` | `concat("PRE_", value)` | 拼接 |
-| `zfill(s, width)` | `zfill(value, 10)` | 零填充 |
-| `lpad(s, width, char)` | `lpad(value, 8, "0")` | 左填充 |
-| `rpad(s, width, char)` | `rpad(value, 8, "0")` | 右填充 |
-| `replace(s, old, new)` | `replace(value, "-", "")` | 替换 |
-| `strip(s)` | `strip(value)` | 去空白 |
-| `int(s)` | `int(value)` | 转整数 |
-| `str(s)` | `str(value)` | 转字符串 |
-| 切片 | `value[-8:]` | Python 切片语法 |
-| 数学 | `value * 2 + 1` | 基本数学运算 |
+| 函数                      | 用法                        | 说明          |
+| :---------------------- | :------------------------ | :---------- |
+| `upper(s)`              | `upper(value)`            | 转大写         |
+| `lower(s)`              | `lower(value)`            | 转小写         |
+| `len(s)`                | `len(value)`              | 获取长度        |
+| `substr(s, start, end)` | `substr(value, 0, 8)`     | 子串          |
+| `concat(*args)`         | `concat("PRE_", value)`   | 拼接          |
+| `zfill(s, width)`       | `zfill(value, 10)`        | 零填充         |
+| `lpad(s, width, char)`  | `lpad(value, 8, "0")`     | 左填充         |
+| `rpad(s, width, char)`  | `rpad(value, 8, "0")`     | 右填充         |
+| `replace(s, old, new)`  | `replace(value, "-", "")` | 替换          |
+| `strip(s)`              | `strip(value)`            | 去空白         |
+| `int(s)`                | `int(value)`              | 转整数         |
+| `str(s)`                | `str(value)`              | 转字符串        |
+| 切片                      | `value[-8:]`              | Python 切片语法 |
+| 数学                      | `value * 2 + 1`           | 基本数学运算      |
 
 > ⚠️ **安全保护**：表达式引擎基于 `simpleeval`，具有 5 秒超时保护，不允许 `import`、`exec` 或文件 I/O 操作。
 
----
+***
 
 ### 教程 5：Transform 脚本 — 极端业务逻辑
 
@@ -547,7 +550,7 @@ tables:
     transform: "./transform_users.py"
 ```
 
----
+***
 
 ### 教程 6：预览与调试
 
@@ -594,7 +597,7 @@ sqlseed inspect app.db --table users --show-mapping
 # └────────────┴─────────┴──────────┴──────────────┴──────────────┘
 ```
 
----
+***
 
 ### 教程 7：快照与回放
 
@@ -611,11 +614,12 @@ sqlseed replay snapshots/2026-04-15_033000_users.yaml
 ```
 
 适用场景：
+
 - 🧪 CI/CD 中需要可重复的测试数据
 - 📋 团队间共享一致的测试环境
 - 🔄 开发时快速重建数据库状态
 
----
+***
 
 ### 教程 8：AI 智能配置（sqlseed-ai 插件）
 
@@ -655,7 +659,7 @@ sqlseed ai-suggest app.db --table bank_cards --output bank_cards.yaml --no-cache
 
 > **💡 环境变量**：支持 `SQLSEED_AI_API_KEY`、`SQLSEED_AI_BASE_URL`、`SQLSEED_AI_MODEL`。默认模型为 `qwen3-coder-plus`。
 
----
+***
 
 ### 教程 9：MCP 服务器集成
 
@@ -671,20 +675,20 @@ python -m mcp_server_sqlseed
 
 **MCP 提供的能力**：
 
-| 类型 | 名称 | 说明 |
-|:---|:---|:---|
-| 📖 Resource | `sqlseed://schema/{db_path}/{table_name}` | 获取表 Schema 的 JSON 表示 |
-| 🔍 Tool | `sqlseed_inspect_schema` | 检查 Schema（列、外键、索引、样本数据、schema_hash） |
-| 🤖 Tool | `sqlseed_generate_yaml` | AI 驱动的 YAML 配置生成（含自纠正） |
-| ⚡ Tool | `sqlseed_execute_fill` | 执行数据生成（支持 YAML 配置字符串） |
+| 类型          | 名称                                        | 说明                                   |
+| :---------- | :---------------------------------------- | :----------------------------------- |
+| 📖 Resource | `sqlseed://schema/{db_path}/{table_name}` | 获取表 Schema 的 JSON 表示                 |
+| 🔍 Tool     | `sqlseed_inspect_schema`                  | 检查 Schema（列、外键、索引、样本数据、schema\_hash） |
+| 🤖 Tool     | `sqlseed_generate_yaml`                   | AI 驱动的 YAML 配置生成（含自纠正）               |
+| ⚡ Tool      | `sqlseed_execute_fill`                    | 执行数据生成（支持 YAML 配置字符串）                |
 
 这意味着你可以在 AI 助手中说：
 
 > "分析 `app.db` 中 `bank_cards` 表的结构，生成 YAML 配置，然后填充 5000 行数据。"
 
-AI 助手会依次调用 `inspect_schema` → `generate_yaml` → `execute_fill`，无需你手动编写任何代码。
+AI 助手会依次调用 `sqlseed_inspect_schema` → `sqlseed_generate_yaml` → `sqlseed_execute_fill`，无需你手动编写任何代码。
 
----
+***
 
 ### 教程 10：自定义 Provider 插件
 
@@ -695,6 +699,8 @@ AI 助手会依次调用 `inspect_schema` → `generate_yaml` → `execute_fill`
 from __future__ import annotations
 from typing import Any
 
+from sqlseed.generators import UnknownGeneratorError
+
 class MyCustomProvider:
     """实现 DataProvider Protocol 即可。不需要继承任何基类。"""
 
@@ -711,14 +717,20 @@ class MyCustomProvider:
     def set_seed(self, seed: int) -> None:
         ...
 
-    def generate_string(self, *, min_length: int = 1, max_length: int = 100, charset: str | None = None) -> str:
-        return "custom_string"
+    def generate(self, type_name: str, **params: Any) -> Any:
+        if type_name == "string":
+            return "custom_string"
+        if type_name == "email":
+            return "user@example.com"
+        raise UnknownGeneratorError(type_name)
 
-    # ... 实现其余 generate_* 方法
+    # ... 按需处理你要支持的 generator 名称
     # 完整 Protocol 参见：src/sqlseed/generators/_protocol.py
 ```
 
-**注册方式 1：通过 `pyproject.toml` entry-point（推荐）**
+如果你想复用内置的 generator name 分发逻辑，而不是手写 `generate()` 的路由，也可以直接继承 `BaseProvider` 后覆盖局部行为。
+
+**注册方式 1：通过** **`pyproject.toml`** **entry-point（推荐）**
 
 ```toml
 [project.entry-points."sqlseed"]
@@ -737,7 +749,7 @@ class MyPlugin:
         registry.register(MyCustomProvider())
 ```
 
----
+***
 
 ## 🖥️ CLI 命令速查
 
@@ -746,7 +758,7 @@ class MyPlugin:
 # 📋 数据生成
 # ═══════════════════════════════════════
 
-# 零配置填充
+# 填充数据（--count 在非 --config 模式下必填）
 sqlseed fill app.db --table users --count 10000
 
 # 完整参数
@@ -758,12 +770,15 @@ sqlseed fill app.db -t users -n 100000 \
     --clear \
     --snapshot
 
-# YAML 配置驱动
+# YAML 配置驱动（count 来自配置文件）
 sqlseed fill --config generate.yaml
 
 # Transform 脚本
 sqlseed fill app.db -t users -n 10000 --transform transform.py
 
+# 开启 debug 日志
+SQLSEED_LOG_LEVEL=DEBUG sqlseed fill app.db -t users -n 10
+
 # ═══════════════════════════════════════
 # 🔍 查看与预览
 # ═══════════════════════════════════════
@@ -796,58 +811,61 @@ sqlseed ai-suggest app.db -t users -o users.yaml
 sqlseed ai-suggest app.db -t users -o users.yaml --model gpt-4o --verify
 ```
 
----
+***
 
-## 🧠 8 级智能列映射
+## 🧠 9 级智能列映射
 
-sqlseed 的核心亮点之一是 `ColumnMapper` 的 8 级策略链。每一列都会按以下优先级尝试匹配：
+sqlseed 的核心亮点之一是 `ColumnMapper` 的 9 级策略链。每一列都会按以下优先级尝试匹配：
 
 ```
 Level 1 │ 用户配置          columns={"email": "email"} 最高优先级
         ▼
 Level 2 │ 自定义精确匹配    通过插件 Hook 注册的规则
         ▼
-Level 3 │ 内置精确匹配      67 条规则：email→email, phone→phone, age→integer...
+Level 3 │ 内置精确匹配      68 条规则：email→email, phone→phone, age→integer...
+        ▼
+Level 4 │ DEFAULT 检查      有默认值 → skip（精确匹配优先于 DEFAULT）
         ▼
-Level 4 │ 自定义模式匹配    通过插件 Hook 注册的正则规则
+Level 5 │ 自定义模式匹配    通过插件 Hook 注册的正则规则
         ▼
-Level 5 │ 内置模式匹配      25 条正则：*_at→datetime, *_id→foreign_key, is_*→boolean...
+Level 6 │ 内置模式匹配      25 条正则：*_at→datetime, *_id→foreign_key, is_*→boolean...
         ▼
-Level 6 │ 跳过              有默认值或可 NULL → skip
+Level 7 │ NULLABLE 回退     可 NULL → skip
         ▼
-Level 7 │ 类型忠实回退      VARCHAR(32)→最长32字符, INT8→0~255, BLOB(1024)→1024字节
+Level 8 │ 类型忠实回退      VARCHAR(32)→最长32字符, INT8→0~255, BLOB(1024)→1024字节
         ▼
-Level 8 │ 默认              string (min=5, max=50)
+Level 9 │ 默认              string (min=5, max=50)
 ```
 
 这意味着：
 
-- 列名 `user_email` → Level 5 模式匹配 `*_email` → `email` 生成器 ✅
-- 列名 `is_verified` → Level 5 模式匹配 `is_*` → `boolean` 生成器 ✅
-- 列类型 `VARCHAR(20)` → Level 7 类型回退 → 最长 20 字符的字符串 ✅
-- 列有 `DEFAULT 1` → Level 6 → 跳过生成 ✅
+- 列名 `user_email` → Level 6 模式匹配 `*_email` → `email` 生成器 ✅
+- 列名 `is_verified` → Level 6 模式匹配 `is_*` → `boolean` 生成器 ✅
+- 列类型 `VARCHAR(20)` → Level 8 类型回退 → 最长 20 字符的字符串 ✅
+- 列有 `DEFAULT 1` → Level 4 → 跳过生成 ✅
+- 列名 `gender` 有 `DEFAULT 'male'` → Level 3 精确匹配 → `choice` 生成器（精确匹配优先于 DEFAULT）✅
 
----
+***
 
 ## 🧩 插件系统
 
 sqlseed 通过 [pluggy](https://pluggy.readthedocs.io/) 提供 11 个 Hook 点，覆盖数据生成全生命周期：
 
-| Hook | firstresult | 触发时机 |
-|:---|:---:|:---|
-| `sqlseed_register_providers` | | 注册自定义数据 Provider |
-| `sqlseed_register_column_mappers` | | 注册自定义列映射规则 |
-| `sqlseed_ai_analyze_table` | ✓ | AI 分析表 Schema（返回列配置建议） |
-| `sqlseed_pre_generate_templates` | ✓ | AI 预计算候选值池 |
-| `sqlseed_before_generate` | | 数据生成循环前 |
-| `sqlseed_after_generate` | | 数据生成完成后 |
-| `sqlseed_transform_row` | | 逐行变换（热路径，注意性能） |
-| `sqlseed_transform_batch` | | 逐批变换（支持链式处理） |
-| `sqlseed_before_insert` | | 每批写入 DB 前 |
-| `sqlseed_after_insert` | | 每批写入 DB 后 |
-| `sqlseed_shared_pool_loaded` | | 跨表共享池加载完成 |
-
----
+| Hook                              | firstresult | 触发时机                   |
+| :-------------------------------- | :---------: | :--------------------- |
+| `sqlseed_register_providers`      |    <br />   | 注册自定义数据 Provider       |
+| `sqlseed_register_column_mappers` |    <br />   | 注册自定义列映射规则             |
+| `sqlseed_ai_analyze_table`        |      ✓      | AI 分析表 Schema（返回列配置建议） |
+| `sqlseed_pre_generate_templates`  |      ✓      | AI 预计算候选值池             |
+| `sqlseed_before_generate`         |    <br />   | 数据生成循环前                |
+| `sqlseed_after_generate`          |    <br />   | 数据生成完成后                |
+| `sqlseed_transform_row`           |    <br />   | 逐行变换（热路径，注意性能）         |
+| `sqlseed_transform_batch`         |    <br />   | 逐批变换（支持链式处理）           |
+| `sqlseed_before_insert`           |    <br />   | 每批写入 DB 前              |
+| `sqlseed_after_insert`            |    <br />   | 每批写入 DB 后              |
+| `sqlseed_shared_pool_loaded`      |    <br />   | SharedPool 注册后（值池已可读）     |
+
+***
 
 ## 🏗️ 项目架构
 
@@ -856,7 +874,7 @@ src/sqlseed/
 ├── __init__.py              # 公共 API (fill, connect, fill_from_config, preview)
 ├── core/                    # ===== 核心编排层 =====
 │   ├── orchestrator.py      # DataOrchestrator 主引擎
-│   ├── mapper.py            # ColumnMapper 8 级策略链
+│   ├── mapper.py            # ColumnMapper 9 级策略链
 │   ├── schema.py            # SchemaInferrer — 推断列、索引、数据分布
 │   ├── relation.py          # RelationResolver + SharedPool — FK 与跨表共享
 │   ├── column_dag.py        # ColumnDAG — 列依赖图 + 拓扑排序
@@ -865,12 +883,12 @@ src/sqlseed/
 │   ├── transform.py         # TransformLoader — 用户脚本动态加载
 │   └── result.py            # GenerationResult 数据类
 ├── generators/              # ===== 数据生成层 =====
-│   ├── _protocol.py         # DataProvider Protocol (24 个 generate_* 方法)
+│   ├── _protocol.py         # DataProvider Protocol + UnknownGeneratorError
 │   ├── registry.py          # ProviderRegistry (entry-point 自动发现)
 │   ├── base_provider.py     # 内置基础生成器（零依赖）
 │   ├── faker_provider.py    # Faker 适配器
 │   ├── mimesis_provider.py  # Mimesis 适配器
-│   └── stream.py            # DataStream 流式生成 + 约束回溯
+│   └── stream.py            # DataStream 流式生成 + 约束回溯 + choice/foreign_key 特判
 ├── database/                # ===== 数据库层 =====
 │   ├── _protocol.py         # DatabaseAdapter Protocol (ColumnInfo, ForeignKeyInfo, IndexInfo)
 │   ├── sqlite_utils_adapter.py   # 默认适配器
@@ -896,10 +914,10 @@ plugins/
 ├── sqlseed-ai/              # AI 插件 — LLM 驱动的智能配置
 │   └── src/sqlseed_ai/      # SchemaAnalyzer, AiConfigRefiner, Few-shot 示例...
 └── mcp-server-sqlseed/      # MCP 服务器 — AI 助手交互
-    └── src/mcp_server_sqlseed/   # FastMCP 工具 (inspect/generate_yaml/execute_fill)
+    └── src/mcp_server_sqlseed/   # FastMCP 工具 (sqlseed_inspect_schema/sqlseed_generate_yaml/sqlseed_execute_fill)
 ```
 
----
+***
 
 ## 🛠️ 开发
 
@@ -919,13 +937,13 @@ mypy src/sqlseed/
 
 测试覆盖了所有核心模块，路径结构与 `src/` 一一对应：`test_core/`、`test_database/`、`test_generators/`、`test_plugins/`、`test_config/`、`test_utils/`。
 
----
+***
 
 ## 📄 License
 
 [AGPL-3.0-or-later](LICENSE)
 
----
+***
 
 <div align="center">