sqlseed 0.2.5__tar.gz → 0.2.6__tar.gz

{sqlseed-0.2.5 → sqlseed-0.2.6}/.gitignore

@@ -59,6 +59,16 @@ dmypy.json
 *.db
 *.sqlite
 *.sqlite3
+# SQLite runtime sidecars
+*.db-wal
+*.db-shm
+*.db-journal
+*.sqlite-wal
+*.sqlite-shm
+*.sqlite-journal
+*.sqlite3-wal
+*.sqlite3-shm
+*.sqlite3-journal
 .sqlseed_cache/
 snapshots/
 .env

{sqlseed-0.2.5 → sqlseed-0.2.6}/CHANGELOG.md

@@ -9,6 +9,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-10-07
+
+### Changed
+
+- Refine Web surface hierarchy, contrast and selection motion, keeping data panels opaque and applying translucent materials to navigation and overlays. Preserve reduced-motion, reduced-transparency and unsupported-filter fallbacks.
+- Make workbench guidance more compact, collapse the table directory on narrow screens, enlarge touch targets and keep generation status, blocking reasons and keyboard focus easier to follow. Shorten the English navigation label from Configurations to Configs without changing its page or actions.
+- Provide English and Simplified Chinese documentation with localized navigation, refreshed package guidance and macOS setup instructions. Expand native macOS regression coverage across Apple Silicon and Intel.
+- Retire obsolete standalone defect probes in favor of the maintained regression suite, and ignore SQLite runtime journal and shared-memory sidecars in the repository.
+
+### Fixed
+
+- Align dependency controls and display generation-locale labels without diagnostic prefixes. Prevent open dropdowns from throwing a `Node.contains` error on window resize.
+- Resolve equivalent macOS SQLite path spellings to the same target without folding distinct filenames or opening an extra database descriptor.
+- Distinguish Apple unified memory from Intel/shared or dedicated GPU memory. Report unified-memory model capacity as a heuristic budget rather than measured free VRAM or verified backend compatibility.
+- Close AI clients, response streams and failed HTTP probes on error paths.
+- Install all five local packages together in the quickstart environment, reject unusable virtual environments and print correctly quoted commands for the selected interpreter and shell.
+- Distinguish AI rule-cache column sets containing separator characters. Use a versioned, unambiguous column-name hash; legacy hashes are safely invalidated and refreshed on the next suggestion request.
+- Adapt terminal progress rendering when the output stream or encoding changes, including UTF-8 capture returning to GBK, and safely display non-ASCII descriptions in narrow terminals without replacing the original generation error.
+- Retain ownership of a newly started Web worker if its resume acknowledgement fails, drain it before returning to maintenance, and restore the recovery page after delayed shutdown. Preserve startup diagnostics for service-only recovery without repeating the component installation.
+
+### Compatibility
+
+- Retain the plugin requirement for Core `>=0.2.5.dev0,<0.3`; install matching package versions. Existing Python, CLI and configuration entry points remain unchanged, while AI rule-cache entries with the old column hash are refreshed on demand.
+- SQLite cycle appends still require existing non-NULL single-column parent keys and retain the 100,000-key source-pool limit. Ordinary acyclic appends still commit batch by batch; a later failure can leave earlier batches committed. This release does not change those generation or transaction boundaries.
+
 ## [0.2.5] - 2026-10-02
 
 ### Added

{sqlseed-0.2.5 → sqlseed-0.2.6}/CHANGELOG.zh-CN.md

@@ -9,6 +9,31 @@
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-10-07
+
+### 变更
+
+- 优化 Web 界面的材质层级、对比度和选择动效，数据面板保持实色，导航与浮层使用半透明材质；保留减少动态效果、减少透明度及不支持背景滤镜时的降级显示。
+- 压缩工作台流程引导，在窄屏折叠数据表目录、扩大触控区域，并改善生成状态、阻塞原因与键盘焦点的呈现。英文导航将 Configurations 简写为 Configs，页面与操作保持不变。
+- 文档站提供英文和简体中文导航，同步包安装说明与 macOS 使用指南；扩展 Apple Silicon 和 Intel Mac 的原生回归覆盖。
+- 用维护中的回归测试替代过期独立缺陷探针，并在仓库中忽略 SQLite 运行时日志及共享内存旁文件。
+
+### 修复
+
+- 对齐依赖视图控件，移除数据语言选项中误加的诊断前缀；修复下拉展开时调整窗口大小触发的 `Node.contains` 异常。
+- 将 macOS 上指向同一 SQLite 文件的不同路径写法识别为同一目标，不混淆不同文件，也不额外打开数据库文件描述符。
+- 正确区分 Apple 统一内存、Intel 共享显存与独立显存；统一内存的模型容量仅作为估算预算，不等同于实测可用显存或已验证的后端兼容性。
+- 在异常路径关闭 AI 客户端、响应流和失败的 HTTP 探测。
+- Quickstart 在同一次解析中安装五个本地包，拒绝无法使用的虚拟环境，并按实际解释器和 shell 输出正确引用的后续命令。
+- 修复 AI 规则缓存对包含分隔符的不同列名集合判断相同的问题，改用带版本且无歧义的列名 hash；旧 hash 安全失效，在下次请求规则建议时重新生成缓存。
+- 终端进度条在输出流或编码变化时重新选择可显示的字符，覆盖 UTF-8 捕获结束后恢复 GBK 的情况；中文描述与窄终端显示也不会因编码异常覆盖原始生成错误。
+- Web 新业务进程启动后若恢复确认失败，继续保留其管理权，安全排空并停止后再返回维护状态，延迟退出后也会重新提供恢复页面；保留启动诊断，重试仅恢复服务，不重复安装组件。
+
+### 兼容性
+
+- 插件沿用 Core `>=0.2.5.dev0,<0.3` 的依赖要求，请使用匹配的包版本。Python、CLI 和配置入口保持兼容，旧列名 hash 对应的 AI 规则缓存会按需重新生成。
+- SQLite 循环追加仍要求已有非空单列父键，来源池上限仍为 100,000 个键。普通无跨表循环的追加仍逐批提交，后续失败可能保留先前已提交的批次；本版不改变这些生成与事务边界。
+
 ## [0.2.5] - 2026-10-02
 
 ### 新增

{sqlseed-0.2.5 → sqlseed-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlseed
-Version: 0.2.5
+Version: 0.2.6
 Summary: Offline declarative SQLite and PostgreSQL test data generation for Python
 Project-URL: Homepage, https://github.com/sunbos/sqlseed
 Project-URL: Documentation, https://sunbos.github.io/sqlseed/
@@ -55,6 +55,7 @@ Requires-Dist: testcontainers>=4.0; extra == 'dev'
 Requires-Dist: tqdm>=4.66; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs-static-i18n<2,>=1.3.1; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
 Provides-Extra: mimesis
 Requires-Dist: mimesis>=18.0; extra == 'mimesis'
@@ -83,7 +84,7 @@ Description-Content-Type: text/markdown
 [![CI](https://github.com/sunbos/sqlseed/actions/workflows/ci.yml/badge.svg)](https://github.com/sunbos/sqlseed/actions/workflows/ci.yml)
 [![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](https://github.com/sunbos/sqlseed/blob/main/LICENSE)
 
-[Quick start](#quick-start) · [Web workbench](#web-workbench) · [CLI](#command-line) · [Documentation](https://sunbos.github.io/sqlseed/)
+[Quick start](#quick-start) · [Web workbench](#web-workbench) · [CLI](#command-line) · [MCP](#mcp-tools) · [Documentation](https://sunbos.github.io/sqlseed/)
 
 </div>
 
@@ -98,20 +99,28 @@ choices, or relationships your application needs in Python or YAML.
 ## Choose an entry point
 
 Requires **Python 3.10+**. Use a virtual environment and install the package for the
-interface you want; you do not need to install every row below. Interface packages
-install Core as a dependency.
+interface you want; you do not need to install every row below. `sqlseed` is the
+offline Core library. The other four packages provide optional interfaces and
+capabilities, and install Core as a dependency.
 
-This README describes version 0.2.5. Check [Releases](https://github.com/sunbos/sqlseed/releases)
+This README describes version 0.2.6. Check [Releases](https://github.com/sunbos/sqlseed/releases)
 for publication status; the [source installation guide](https://sunbos.github.io/sqlseed/guide/#source-installation)
 covers unpublished candidates.
 
-| I want to… | Install | Start here |
+| Package and purpose | Install | Start here |
 | --- | --- | --- |
-| Generate data from Python | `python -m pip install sqlseed` | [Quick start](#quick-start) |
-| Use a browser | `python -m pip install sqlseed-web` | [Web workbench](#web-workbench) |
-| Work in a terminal | `python -m pip install sqlseed-cli` | [Command line](#command-line) |
-| Ask a model to suggest or repair rules | `python -m pip install sqlseed-ai` | [AI assistance](#optional-ai-assistance) |
-| Use rule-driven tools from an MCP client | `python -m pip install mcp-server-sqlseed` | [MCP setup](https://sunbos.github.io/sqlseed/guide/#mcp-server) |
+| **Core — `sqlseed`**: infer rules, preview, and generate data through Python or configuration files | `python -m pip install sqlseed` | [Quick start](#quick-start) |
+| **Web — `sqlseed-web`**: edit rules, inspect relationships, preview, and review runs in a browser | `python -m pip install sqlseed-web` | [Web workbench](#web-workbench) |
+| **CLI — `sqlseed-cli`**: inspect schema, fill tables, and save or replay configurations from a terminal | `python -m pip install sqlseed-cli` | [Command line](#command-line) |
+| **AI — `sqlseed-ai`**: use a configured model to suggest or repair generation rules | `python -m pip install sqlseed-ai` | [AI assistance](#optional-ai-assistance) |
+| **MCP — `mcp-server-sqlseed`**: expose rule-driven YAML generation and data filling to an MCP client | `python -m pip install mcp-server-sqlseed` | [MCP tools](#mcp-tools) |
+
+Web and the rule-driven MCP server can each be installed without CLI or AI.
+Installing AI also installs CLI and adds its AI commands. The Core `sqlseed[all]`
+extra groups optional dependencies; it does not install all four packages above.
+
+On macOS, start with the [macOS setup guide](https://sunbos.github.io/sqlseed/macos/)
+for native Python, virtual environments, Intel dependencies, and desktop MCP paths.
 
 Faker is included with Core and is selected explicitly in the examples below.
 Mimesis is optional: install it with `python -m pip install 'sqlseed[mimesis]'`.
@@ -159,7 +168,7 @@ Names and email addresses are inferred from the columns. The database assigns th
 primary keys. Each run appends another 100 rows; it does not clear the table.
 Check both `result.count` and `result.errors` after generation.
 
-In version 0.2.5, `sqlseed.FillOptions(provider="faker", seed=42)`
+Since version 0.2.5, `sqlseed.FillOptions(provider="faker", seed=42)`
 can share generation settings across `fill(..., options=settings)` calls.
 Existing individual keywords remain supported; see the
 [Python API reference](https://sunbos.github.io/sqlseed/api/#filloptions).
@@ -215,16 +224,39 @@ python -m pip install sqlseed-web
 sqlseed-web
 ```
 
-Open **[http://127.0.0.1:8630](http://127.0.0.1:8630)**, connect to an existing database
-(such as the `demo.db` above), select tables, edit rules, preview, and generate.
+Open **[http://127.0.0.1:8630](http://127.0.0.1:8630)** and connect to an existing
+SQLite or PostgreSQL database, such as the `demo.db` above.
+For PostgreSQL, install the driver in the same Python environment before starting
+the workbench: `python -m pip install 'sqlseed[postgres]'`.
 The `sqlseed-web` command is installed with the package; no custom startup script
 or source checkout is required.
 
-The workbench includes saved configurations, relationship views, and run history.
-AI is optional, and manual editing, preview, and generation work without it.
-Version 0.2.5 offers Simplified Chinese and English from the top
+Select the tables to generate, set row counts, and edit column rules. Use the
+relationship view to inspect foreign keys and check dependencies. Preview samples
+without writing to the database, then review the generation plan and confirm the
+write. Save configurations for reuse and inspect the results in run history.
+
+![English Web workbench relationship view for a fictional SQLite order demo](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-light.png)
+
+The actual 0.2.5 interface with the repository's
+[fictional SQLite order example](https://github.com/sunbos/sqlseed/tree/main/examples/order_workflow).
+[Open the full-size PNG](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-light.png)
+or [see the read-only sample preview in the dark theme](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-dark.png).
+Previewed samples are generated for inspection and are not inserted into the database.
+
+Since version 0.2.5, the workbench offers Simplified Chinese and English from the top
 bar. Changing the interface language keeps your edits and does not change the
-data language and region used for generation.
+data language and region used for generation. Light and dark themes are also available.
+
+Manual editing, preview, and generation work without AI. To add the optional
+configuration assistant, install AI in the same environment:
+
+```bash
+python -m pip install 'sqlseed-web[ai]'
+```
+
+Then configure a model service in settings. AI suggestions remain available for
+review before you apply them; generation uses the rules you have confirmed.
 See the [Web guide](https://sunbos.github.io/sqlseed/web-workbench/) for connection
 settings, optional components, and deployment requirements.
 
@@ -240,7 +272,7 @@ sqlseed fill demo.db -t users -n 100 --provider faker --no-ai
 ```
 
 Use `sqlseed --help` or `sqlseed <command> --help` for options. The CLI also supports
-configuration templates, snapshots, and replay; see the
+configuration templates, configuration snapshots, and replay; see the
 [CLI reference](https://sunbos.github.io/sqlseed/guide/#cli-reference).
 Installing Core alone provides the Python API; `sqlseed-cli` supplies the `sqlseed`
 command.
@@ -290,8 +322,35 @@ before relying on it.
 
 See the [AI command reference](https://sunbos.github.io/sqlseed/guide/#ai-suggest)
 and [backend and validation guide](https://sunbos.github.io/sqlseed/gemma4-integration/).
-For model-assisted MCP tools, use the separate server provided by `sqlseed-ai[mcp]`;
-[MCP setup](https://sunbos.github.io/sqlseed/guide/#mcp-server) explains both servers.
+
+## MCP tools
+
+For rule-driven tools that need no model service, install and start the stdio server:
+
+```bash
+python -m pip install mcp-server-sqlseed
+mcp-server-sqlseed
+```
+
+Configure your MCP client to launch `mcp-server-sqlseed` from that environment;
+use the executable's absolute path if the client does not inherit its PATH.
+The server provides `sqlseed_generate_yaml` to prepare rules for review and
+`sqlseed_execute_fill` to write data to the specified existing table. Check the
+returned `count` and `errors` after a fill.
+
+Model-assisted tools use a separate stdio server supplied by the AI package:
+
+```bash
+python -m pip install 'sqlseed-ai[mcp]'
+mcp-server-sqlseed-ai
+```
+
+Configure the AI backend for that process using the [AI setup guide](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/README.md).
+It provides AI YAML suggestions, table analysis, an analyze-and-fill tool, and
+model/backend availability information. Installing AI does not add these tools
+to the rule-driven server; configure both processes if you want both tool sets.
+See [MCP setup](https://sunbos.github.io/sqlseed/guide/#mcp-server) for client
+configuration and tool details.
 
 ## Working with your own database
 

{sqlseed-0.2.5 → sqlseed-0.2.6}/README.md

@@ -17,7 +17,7 @@
 [![CI](https://github.com/sunbos/sqlseed/actions/workflows/ci.yml/badge.svg)](https://github.com/sunbos/sqlseed/actions/workflows/ci.yml)
 [![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](https://github.com/sunbos/sqlseed/blob/main/LICENSE)
 
-[Quick start](#quick-start) · [Web workbench](#web-workbench) · [CLI](#command-line) · [Documentation](https://sunbos.github.io/sqlseed/)
+[Quick start](#quick-start) · [Web workbench](#web-workbench) · [CLI](#command-line) · [MCP](#mcp-tools) · [Documentation](https://sunbos.github.io/sqlseed/)
 
 </div>
 
@@ -32,20 +32,28 @@ choices, or relationships your application needs in Python or YAML.
 ## Choose an entry point
 
 Requires **Python 3.10+**. Use a virtual environment and install the package for the
-interface you want; you do not need to install every row below. Interface packages
-install Core as a dependency.
+interface you want; you do not need to install every row below. `sqlseed` is the
+offline Core library. The other four packages provide optional interfaces and
+capabilities, and install Core as a dependency.
 
-This README describes version 0.2.5. Check [Releases](https://github.com/sunbos/sqlseed/releases)
+This README describes version 0.2.6. Check [Releases](https://github.com/sunbos/sqlseed/releases)
 for publication status; the [source installation guide](https://sunbos.github.io/sqlseed/guide/#source-installation)
 covers unpublished candidates.
 
-| I want to… | Install | Start here |
+| Package and purpose | Install | Start here |
 | --- | --- | --- |
-| Generate data from Python | `python -m pip install sqlseed` | [Quick start](#quick-start) |
-| Use a browser | `python -m pip install sqlseed-web` | [Web workbench](#web-workbench) |
-| Work in a terminal | `python -m pip install sqlseed-cli` | [Command line](#command-line) |
-| Ask a model to suggest or repair rules | `python -m pip install sqlseed-ai` | [AI assistance](#optional-ai-assistance) |
-| Use rule-driven tools from an MCP client | `python -m pip install mcp-server-sqlseed` | [MCP setup](https://sunbos.github.io/sqlseed/guide/#mcp-server) |
+| **Core — `sqlseed`**: infer rules, preview, and generate data through Python or configuration files | `python -m pip install sqlseed` | [Quick start](#quick-start) |
+| **Web — `sqlseed-web`**: edit rules, inspect relationships, preview, and review runs in a browser | `python -m pip install sqlseed-web` | [Web workbench](#web-workbench) |
+| **CLI — `sqlseed-cli`**: inspect schema, fill tables, and save or replay configurations from a terminal | `python -m pip install sqlseed-cli` | [Command line](#command-line) |
+| **AI — `sqlseed-ai`**: use a configured model to suggest or repair generation rules | `python -m pip install sqlseed-ai` | [AI assistance](#optional-ai-assistance) |
+| **MCP — `mcp-server-sqlseed`**: expose rule-driven YAML generation and data filling to an MCP client | `python -m pip install mcp-server-sqlseed` | [MCP tools](#mcp-tools) |
+
+Web and the rule-driven MCP server can each be installed without CLI or AI.
+Installing AI also installs CLI and adds its AI commands. The Core `sqlseed[all]`
+extra groups optional dependencies; it does not install all four packages above.
+
+On macOS, start with the [macOS setup guide](https://sunbos.github.io/sqlseed/macos/)
+for native Python, virtual environments, Intel dependencies, and desktop MCP paths.
 
 Faker is included with Core and is selected explicitly in the examples below.
 Mimesis is optional: install it with `python -m pip install 'sqlseed[mimesis]'`.
@@ -93,7 +101,7 @@ Names and email addresses are inferred from the columns. The database assigns th
 primary keys. Each run appends another 100 rows; it does not clear the table.
 Check both `result.count` and `result.errors` after generation.
 
-In version 0.2.5, `sqlseed.FillOptions(provider="faker", seed=42)`
+Since version 0.2.5, `sqlseed.FillOptions(provider="faker", seed=42)`
 can share generation settings across `fill(..., options=settings)` calls.
 Existing individual keywords remain supported; see the
 [Python API reference](https://sunbos.github.io/sqlseed/api/#filloptions).
@@ -149,16 +157,39 @@ python -m pip install sqlseed-web
 sqlseed-web
 ```
 
-Open **[http://127.0.0.1:8630](http://127.0.0.1:8630)**, connect to an existing database
-(such as the `demo.db` above), select tables, edit rules, preview, and generate.
+Open **[http://127.0.0.1:8630](http://127.0.0.1:8630)** and connect to an existing
+SQLite or PostgreSQL database, such as the `demo.db` above.
+For PostgreSQL, install the driver in the same Python environment before starting
+the workbench: `python -m pip install 'sqlseed[postgres]'`.
 The `sqlseed-web` command is installed with the package; no custom startup script
 or source checkout is required.
 
-The workbench includes saved configurations, relationship views, and run history.
-AI is optional, and manual editing, preview, and generation work without it.
-Version 0.2.5 offers Simplified Chinese and English from the top
+Select the tables to generate, set row counts, and edit column rules. Use the
+relationship view to inspect foreign keys and check dependencies. Preview samples
+without writing to the database, then review the generation plan and confirm the
+write. Save configurations for reuse and inspect the results in run history.
+
+![English Web workbench relationship view for a fictional SQLite order demo](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-light.png)
+
+The actual 0.2.5 interface with the repository's
+[fictional SQLite order example](https://github.com/sunbos/sqlseed/tree/main/examples/order_workflow).
+[Open the full-size PNG](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-light.png)
+or [see the read-only sample preview in the dark theme](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-en-dark.png).
+Previewed samples are generated for inspection and are not inserted into the database.
+
+Since version 0.2.5, the workbench offers Simplified Chinese and English from the top
 bar. Changing the interface language keeps your edits and does not change the
-data language and region used for generation.
+data language and region used for generation. Light and dark themes are also available.
+
+Manual editing, preview, and generation work without AI. To add the optional
+configuration assistant, install AI in the same environment:
+
+```bash
+python -m pip install 'sqlseed-web[ai]'
+```
+
+Then configure a model service in settings. AI suggestions remain available for
+review before you apply them; generation uses the rules you have confirmed.
 See the [Web guide](https://sunbos.github.io/sqlseed/web-workbench/) for connection
 settings, optional components, and deployment requirements.
 
@@ -174,7 +205,7 @@ sqlseed fill demo.db -t users -n 100 --provider faker --no-ai
 ```
 
 Use `sqlseed --help` or `sqlseed <command> --help` for options. The CLI also supports
-configuration templates, snapshots, and replay; see the
+configuration templates, configuration snapshots, and replay; see the
 [CLI reference](https://sunbos.github.io/sqlseed/guide/#cli-reference).
 Installing Core alone provides the Python API; `sqlseed-cli` supplies the `sqlseed`
 command.
@@ -224,8 +255,35 @@ before relying on it.
 
 See the [AI command reference](https://sunbos.github.io/sqlseed/guide/#ai-suggest)
 and [backend and validation guide](https://sunbos.github.io/sqlseed/gemma4-integration/).
-For model-assisted MCP tools, use the separate server provided by `sqlseed-ai[mcp]`;
-[MCP setup](https://sunbos.github.io/sqlseed/guide/#mcp-server) explains both servers.
+
+## MCP tools
+
+For rule-driven tools that need no model service, install and start the stdio server:
+
+```bash
+python -m pip install mcp-server-sqlseed
+mcp-server-sqlseed
+```
+
+Configure your MCP client to launch `mcp-server-sqlseed` from that environment;
+use the executable's absolute path if the client does not inherit its PATH.
+The server provides `sqlseed_generate_yaml` to prepare rules for review and
+`sqlseed_execute_fill` to write data to the specified existing table. Check the
+returned `count` and `errors` after a fill.
+
+Model-assisted tools use a separate stdio server supplied by the AI package:
+
+```bash
+python -m pip install 'sqlseed-ai[mcp]'
+mcp-server-sqlseed-ai
+```
+
+Configure the AI backend for that process using the [AI setup guide](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/README.md).
+It provides AI YAML suggestions, table analysis, an analyze-and-fill tool, and
+model/backend availability information. Installing AI does not add these tools
+to the rule-driven server; configure both processes if you want both tool sets.
+See [MCP setup](https://sunbos.github.io/sqlseed/guide/#mcp-server) for client
+configuration and tool details.
 
 ## Working with your own database
 

{sqlseed-0.2.5 → sqlseed-0.2.6}/README.zh-CN.md

@@ -17,7 +17,7 @@
 [![CI](https://github.com/sunbos/sqlseed/actions/workflows/ci.yml/badge.svg)](https://github.com/sunbos/sqlseed/actions/workflows/ci.yml)
 [![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](https://github.com/sunbos/sqlseed/blob/main/LICENSE)
 
-[快速开始](#快速开始) · [Web 工作台](#web-工作台) · [命令行](#命令行) · [完整文档](https://sunbos.github.io/sqlseed/)
+[快速开始](#快速开始) · [Web 工作台](#web-工作台) · [命令行](#命令行) · [MCP](#mcp-工具) · [完整文档](https://sunbos.github.io/sqlseed/zh-CN/)
 
 </div>
 
@@ -31,22 +31,29 @@ sqlseed 向已有数据库表中填充测试数据。它会为姓名、邮箱等
 ## 选择使用入口
 
 需要 **Python 3.10+**。建议使用虚拟环境，按自己的使用方式安装对应包，
-无需把下表中的包全部安装。各入口包会自动安装所需的 Core。
+无需把下表中的包全部安装。`sqlseed` 是离线 Core 库，其余四个包提供可选入口与能力，
+会自动安装所需的 Core。
 
-本文对应 0.2.5 版本，发布状态以 [Releases](https://github.com/sunbos/sqlseed/releases) 为准；
-尚未发布的候选版本按[源码安装指南](https://sunbos.github.io/sqlseed/guide/#source-installation)体验。
+本文对应 0.2.6 版本，发布状态以 [Releases](https://github.com/sunbos/sqlseed/releases) 为准；
+尚未发布的候选版本按[源码安装指南](https://sunbos.github.io/sqlseed/zh-CN/guide/#source-installation)体验。
 
-| 我想要…… | 安装命令 | 从这里开始 |
+| 包与用途 | 安装命令 | 从这里开始 |
 | --- | --- | --- |
-| 在 Python 中生成数据 | `python -m pip install sqlseed` | [快速开始](#快速开始) |
-| 在浏览器中操作 | `python -m pip install sqlseed-web` | [Web 工作台](#web-工作台) |
-| 在终端中操作 | `python -m pip install sqlseed-cli` | [命令行](#命令行) |
-| 让模型建议或修复规则 | `python -m pip install sqlseed-ai` | [可选的 AI 辅助](#可选的-ai-辅助) |
-| 在 MCP 客户端中使用规则工具 | `python -m pip install mcp-server-sqlseed` | [MCP 配置](https://sunbos.github.io/sqlseed/guide/#mcp-server) |
+| **Core — `sqlseed`**：通过 Python 或配置文件推断规则、预览并生成数据 | `python -m pip install sqlseed` | [快速开始](#快速开始) |
+| **Web — `sqlseed-web`**：在浏览器中编辑规则、查看关系、预览和查看运行结果 | `python -m pip install sqlseed-web` | [Web 工作台](#web-工作台) |
+| **CLI — `sqlseed-cli`**：在终端检查结构、填充数据、保存和重放配置 | `python -m pip install sqlseed-cli` | [命令行](#命令行) |
+| **AI — `sqlseed-ai`**：通过已配置的模型建议或修复生成规则 | `python -m pip install sqlseed-ai` | [可选的 AI 辅助](#可选的-ai-辅助) |
+| **MCP — `mcp-server-sqlseed`**：向 MCP 客户端提供规则型 YAML 生成和数据填充工具 | `python -m pip install mcp-server-sqlseed` | [MCP 工具](#mcp-工具) |
+
+Web 和规则型 MCP 均可独立安装，无需 CLI 或 AI。安装 AI 会自动安装 CLI 并增加 AI 命令。
+`sqlseed[all]` 是 Core 的一组选装依赖，不代表安装上面的全部四个包。
+
+macOS 用户可先阅读 [macOS 安装与开发指南](https://sunbos.github.io/sqlseed/zh-CN/macos/)，
+了解原生 Python、虚拟环境、Intel 依赖和桌面 MCP 路径配置。
 
 Core 已包含 Faker，下面的示例会明确选择它。
 Mimesis 是可选依赖，可通过 `python -m pip install 'sqlseed[mimesis]'` 安装。
-旧版本用户请先看[升级指南](https://sunbos.github.io/sqlseed/migration.zh-CN/)。
+旧版本用户请先看[升级指南](https://sunbos.github.io/sqlseed/zh-CN/migration/)。
 
 ## 快速开始
 
@@ -88,9 +95,9 @@ print(result.count, result.errors)  # 100 []
 姓名和邮箱的生成规则由字段名推断，主键由数据库分配。
 每次运行会继续追加 100 行，不会清空表。生成后应同时检查 `result.count` 和 `result.errors`。
 
-0.2.5 版本可用 `sqlseed.FillOptions(provider="faker", seed=42)` 复用生成设置，
+自 0.2.5 起，可用 `sqlseed.FillOptions(provider="faker", seed=42)` 复用生成设置，
 通过 `fill(..., options=settings)` 传入。原有单独关键字仍可使用，详见
-[Python API 参考](https://sunbos.github.io/sqlseed/api/#filloptions)。
+[Python API 参考](https://sunbos.github.io/sqlseed/zh-CN/api/#filloptions)。
 
 只想查看样例、不写入数据库时，可以使用：
 
@@ -131,8 +138,8 @@ for result in sqlseed.fill_from_config("generate.yaml"):
     print(result.count, result.errors)
 ```
 
-[配置指南](https://sunbos.github.io/sqlseed/guide/#yaml-configuration)介绍了取值范围、
-加权选择、派生列和跨表关系；完整名称与参数见[生成器参考](https://sunbos.github.io/sqlseed/guide/#generators)。
+[配置指南](https://sunbos.github.io/sqlseed/zh-CN/guide/#yaml-configuration)介绍了取值范围、
+加权选择、派生列和跨表关系；完整名称与参数见[生成器参考](https://sunbos.github.io/sqlseed/zh-CN/guide/#generators)。
 
 ## Web 工作台
 
@@ -141,13 +148,35 @@ python -m pip install sqlseed-web
 sqlseed-web
 ```
 
-打开 **[http://127.0.0.1:8630](http://127.0.0.1:8630)**，连接已有数据库
-（例如上面创建的 `demo.db`），选择表、编辑规则、预览，再生成数据。
+打开 **[http://127.0.0.1:8630](http://127.0.0.1:8630)**，连接已有的 SQLite 或 PostgreSQL
+数据库，例如上面创建的 `demo.db`。
+使用 PostgreSQL 时，请在启动工作台前，在同一个 Python 环境中安装驱动：
+`python -m pip install 'sqlseed[postgres]'`。
 `sqlseed-web` 命令随安装包提供，不需要自定义启动脚本，也不需要仓库源码。
 
-工作台还提供配置保存、关系图和运行记录。AI 为可选功能，未安装时仍可手动编辑、预览和生成。
-0.2.5 版本可从顶栏切换简体中文与 English；切换界面语言保留正在编辑的内容，不改变生成配置中的数据语言与地区。
-连接设置、可选组件与部署要求见 [Web 使用指南](https://sunbos.github.io/sqlseed/web-workbench/)。
+勾选要生成的表，设置行数并编辑字段规则；通过关系图查看外键并检查依赖。
+先预览样例，预览不会写入数据库；再查看生成计划，确认后写入。
+配置可以保存复用，执行结果可在运行记录中查看。
+
+![中文 Web 工作台关系图：虚构的 SQLite 订单演示](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-zh-CN-light.png)
+
+0.2.5 正式界面的实际截图，使用仓库中的
+[虚构 SQLite 订单示例](https://github.com/sunbos/sqlseed/tree/main/examples/order_workflow)。
+[查看原尺寸高清 PNG](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-zh-CN-light.png)，
+或[查看深色主题下的只读样例预览](https://raw.githubusercontent.com/sunbos/sqlseed/992ba0e733d5b41f73e37b0a9d02d573d6e2bb23/docs/assets/screenshots/web-workbench-zh-CN-dark.png)。
+预览样例仅供检查，不会插入数据库。
+
+自 0.2.5 起，可从顶栏切换简体中文与 English；切换界面语言保留正在编辑的内容，
+不改变生成配置中的数据语言与地区。界面也提供浅色和深色主题。
+
+未安装 AI 时，手动编辑、预览与生成均可使用。需要可选的配置助手时，在同一环境中安装：
+
+```bash
+python -m pip install 'sqlseed-web[ai]'
+```
+
+随后在设置中配置模型服务。AI 建议经审阅和应用后进入配置，生成时使用你已确认的规则。
+连接设置、可选组件与部署要求见 [Web 使用指南](https://sunbos.github.io/sqlseed/zh-CN/web-workbench/)。
 
 ## 命令行
 
@@ -161,7 +190,7 @@ sqlseed fill demo.db -t users -n 100 --provider faker --no-ai
 ```
 
 运行 `sqlseed --help` 或 `sqlseed <命令> --help` 查看选项。
-配置模板、快照和重放的用法见 [CLI 参考](https://sunbos.github.io/sqlseed/guide/#cli-reference)。
+配置模板、配置快照和重放的用法见 [CLI 参考](https://sunbos.github.io/sqlseed/zh-CN/guide/#cli-reference)。
 只安装 Core 时提供 Python API，`sqlseed` 命令由 `sqlseed-cli` 包提供。
 
 ## PostgreSQL
@@ -187,7 +216,7 @@ print(result.count, result.errors)
 ```
 
 SQLite 路径与 `url` 不能同时传入。支持的外键结构和各入口差异见
-[支持范围](https://sunbos.github.io/sqlseed/maintainable-release/)。
+[支持范围](https://sunbos.github.io/sqlseed/zh-CN/maintainable-release/)。
 
 ## 可选的 AI 辅助
 
@@ -204,10 +233,33 @@ SQLite 路径与 `url` 不能同时传入。支持的外键结构和各入口差
 其他约束可能需要显式配置或模型建议，不能把它理解为任意 SQL CHECK 的求解器。
 使用候选配置前，仍需审阅规则并验证实际生成的数据。
 
-具体用法见 [AI 命令参考](https://sunbos.github.io/sqlseed/guide/#ai-suggest)和
-[模型后端与校验说明](https://sunbos.github.io/sqlseed/gemma4-integration.zh-CN/)。
-如需模型辅助的 MCP 工具，使用 `sqlseed-ai[mcp]` 提供的独立服务；
-[MCP 配置](https://sunbos.github.io/sqlseed/guide/#mcp-server)说明了两种服务的区别。
+具体用法见 [AI 命令参考](https://sunbos.github.io/sqlseed/zh-CN/guide/#ai-suggest)和
+[模型后端与校验说明](https://sunbos.github.io/sqlseed/zh-CN/gemma4-integration/)。
+
+## MCP 工具
+
+需要不调用模型的规则工具时，安装并启动 stdio 服务：
+
+```bash
+python -m pip install mcp-server-sqlseed
+mcp-server-sqlseed
+```
+
+在 MCP 客户端中配置该环境的 `mcp-server-sqlseed` 可执行文件；客户端未继承该环境的 PATH 时，
+使用可执行文件的绝对路径。服务提供 `sqlseed_generate_yaml` 供你准备和审阅规则，
+以及向指定已有表写入数据的 `sqlseed_execute_fill`。填充后检查返回的 `count` 与 `errors`。
+
+需要模型辅助工具时，使用 AI 包提供的另一个 stdio 服务：
+
+```bash
+python -m pip install 'sqlseed-ai[mcp]'
+mcp-server-sqlseed-ai
+```
+
+按 [AI 配置指南](https://github.com/sunbos/sqlseed/blob/main/plugins/sqlseed-ai/README.zh-CN.md)
+为该进程配置模型后端。它提供 AI YAML 建议、表分析、分析后直接填充，以及模型和后端可用性信息。
+安装 AI 不会向规则型服务注入这些工具；需要两组工具时，在客户端分别配置两个进程。
+客户端配置与工具详情见 [MCP 配置](https://sunbos.github.io/sqlseed/zh-CN/guide/#mcp-server)。
 
 ## 用于自己的数据库时
 
@@ -216,17 +268,17 @@ SQLite 路径与 `url` 不能同时传入。支持的外键结构和各入口差
 - **保持复现条件一致。** 只有 seed 相同，并不能保证跨依赖版本、provider、配置或初始数据得到完全相同的结果。
 
 复杂 CHECK 和复合外键的支持范围因数据库而异，具体边界与写入行为见
-[支持与维护说明](https://sunbos.github.io/sqlseed/maintainable-release/)。
+[支持与维护说明](https://sunbos.github.io/sqlseed/zh-CN/maintainable-release/)。
 
 ## 文档导航
 
 | 下一步 | 文档 |
 | --- | --- |
-| 配置生成器、表达式与多表数据 | [用户指南](https://sunbos.github.io/sqlseed/guide/) |
-| 使用 `fill`、`FillOptions`、`preview`、`connect`、`fill_from_config`、`load_config` | [Python API 参考](https://sunbos.github.io/sqlseed/api/) |
+| 配置生成器、表达式与多表数据 | [用户指南](https://sunbos.github.io/sqlseed/zh-CN/guide/) |
+| 使用 `fill`、`FillOptions`、`preview`、`connect`、`fill_from_config`、`load_config` | [Python API 参考](https://sunbos.github.io/sqlseed/zh-CN/api/) |
 | 跑通完整的多表示例 | [订单工作流](https://github.com/sunbos/sqlseed/tree/main/examples/order_workflow) |
-| 了解包边界和扩展 hooks | [架构文档](https://sunbos.github.io/sqlseed/architecture.zh-CN/) |
-| 升级已有安装 | [迁移指南](https://sunbos.github.io/sqlseed/migration.zh-CN/) |
+| 了解包边界和扩展 hooks | [架构文档](https://sunbos.github.io/sqlseed/zh-CN/architecture/) |
+| 升级已有安装 | [迁移指南](https://sunbos.github.io/sqlseed/zh-CN/migration/) |
 | 查看已发布版本与变更 | [Releases](https://github.com/sunbos/sqlseed/releases) |
 
 ## 参与开发

{sqlseed-0.2.5 → sqlseed-0.2.6}/pyproject.toml

@@ -78,6 +78,7 @@ dev = [
 ]
 docs = [
     "mkdocs-material>=9.0",
+    "mkdocs-static-i18n>=1.3.1,<2",
     "mkdocstrings[python]>=0.25",
 ]
 

{sqlseed-0.2.5 → sqlseed-0.2.6}/src/sqlseed/_utils/AGENTS.md

@@ -19,6 +19,7 @@
 - logger 首次使用后会缓存绑定配置；宿主应在 import 或首次使用前配置日志，不能假设后续 `configure_logging()` 会更新已缓存 logger。
 - [metrics.py](metrics.py)：`MetricsCollector` 聚合 count/total/min/max/avg；保留单次遍历与按名称过滤。
 - [progress.py](progress.py)：通过 `create_progress()` 选 backend，disabled → Null，Jupyter 且有 tqdm → notebook backend，其他环境且有 Rich → Rich；缺少对应可选库均降级为 Null，保留编码不支持时的 ASCII fallback。
+- 输出流及其编码可能在捕获、重定向期间变化；已经创建的进度显示也需按实际输出选择安全字符，不能用首次编码检测结果覆盖后续状态或掩盖原始业务异常。
 - tqdm 是 notebook 可选依赖，Rich 由 CLI 依赖提供；不能让缺失进度显示库破坏 core 的 import 或生成路径。
 - `get_cache_dir()` 优先 `SQLSEED_CACHE_DIR`，否则遵循 macOS/Linux/Windows 路径约定；只返回路径，调用方负责创建目录。
 - [daemon_task.py](daemon_task.py) 用 Future 管理单个 daemon worker 的结果与异常；超时只停止等待，不终止工作。需要在 worker 内执行的完成回调通过构造参数 `on_done` 在线程启动前注册，避免快速任务完成后回调落到调用线程。进程控制异常也必须传回等待方，不能变成 `None` 成功结果。

{sqlseed-0.2.5 → sqlseed-0.2.6}/src/sqlseed/_utils/progress.py

@@ -11,6 +11,7 @@ import builtins
 import importlib
 import sys
 from abc import ABC, abstractmethod
+from copy import copy
 from functools import lru_cache
 from importlib.util import find_spec
 from typing import Any, Literal
@@ -35,6 +36,7 @@ except ImportError:
 # ``None`` (when absent), allowing runtime ``is None`` guards and
 # instantiation in RichProgressBackend.__init__.
 try:
+    _GET_CONSOLE = importlib.import_module("rich").get_console
     _rich_progress_module = importlib.import_module("rich.progress")
     _PROGRESS_CLASS = _rich_progress_module.Progress
     _BAR_COLUMN_CLASS = _rich_progress_module.BarColumn
@@ -43,6 +45,7 @@ try:
     _TIME_REMAINING_COLUMN_CLASS = _rich_progress_module.TimeRemainingColumn
     _TRANSFER_SPEED_COLUMN_CLASS = _rich_progress_module.TransferSpeedColumn
 except ImportError:
+    _GET_CONSOLE = None
     _PROGRESS_CLASS = None
     _BAR_COLUMN_CLASS = None
     _SPINNER_COLUMN_CLASS = None
@@ -98,18 +101,18 @@ def _is_jupyter_shell(shell: Any) -> bool:
     return "IPKernelApp" in config
 
 
-@lru_cache(maxsize=1)
-def _can_render_unicode() -> bool:
-    """Check whether stdout can encode characters used by Rich progress bars.
+def _can_render_unicode(*, encoding: str | None = None) -> bool:
+    """Check whether the current output can encode Rich progress characters.
 
     Rich's default ``SpinnerColumn`` uses Braille patterns (e.g. ``⠋`` U+280B)
     and ``BarColumn`` uses block elements (``█`` U+2588, ``░`` U+2591).  On
     Windows consoles with GBK / GB2312 / Big5 encodings these characters cause
     ``UnicodeEncodeError``.  This helper probes the actual encoding so that
-    ``create_progress()`` can fall back to an ASCII-safe layout.
+    rendering can fall back to an ASCII-safe layout. Do not cache the result:
+    stdout may be redirected or its encoding reconfigured during a run.
     """
     try:
-        encoding = getattr(sys.stdout, "encoding", None) or "utf-8"
+        encoding = encoding or getattr(sys.stdout, "encoding", None) or "utf-8"
         "\u280b\u2588\u2591".encode(encoding)
         return True
     except (UnicodeEncodeError, LookupError, TypeError):
@@ -184,6 +187,62 @@ class NullProgressBackend(ProgressBackend):
 # ---------------------------------------------------------------------------
 
 
+class _EncodingAwareColumn:
+    """Select a real Rich column using the output encoding at render time."""
+
+    def __init__(self, unicode_column: Any, ascii_column: Any, *, console: Any) -> None:
+        """Retain both layouts so later stream redirection can change the chosen column."""
+        self._unicode_column = unicode_column
+        self._ascii_column = ascii_column
+        self._console = console
+
+    def _current_column(self) -> Any:
+        """Choose a column using the console's current encoding rather than its initial stream."""
+        if _can_render_unicode(encoding=self._console.encoding):
+            return self._unicode_column
+        return self._ascii_column
+
+    def get_table_column(self) -> Any:
+        """Use the selected column's layout, including an empty fallback bar."""
+        column = self._current_column().get_table_column().copy()
+        if not _can_render_unicode(encoding=self._console.encoding):
+            # Rich's default truncation inserts a Unicode ellipsis, even
+            # when the actual text and spinner are entirely ASCII.
+            column.overflow = "crop"
+        return column
+
+    def __call__(self, task: Any) -> Any:
+        """Render safely even when an existing progress changes output streams."""
+        return self._current_column()(task)
+
+
+class _EncodingAwareDescriptionColumn:
+    """Escape unencodable display text without changing the original task."""
+
+    def __init__(self, column: Any, *, console: Any) -> None:
+        """Wrap the display column while leaving task descriptions available in their original form."""
+        self._column = column
+        self._console = console
+
+    def get_table_column(self) -> Any:
+        """Keep the description column's normal Rich layout."""
+        return self._column.get_table_column()
+
+    def __call__(self, task: Any) -> Any:
+        """Use the current output encoding, including during exception cleanup."""
+        description: str = task.description
+        encoding = self._console.encoding
+        try:
+            safe_description = description.encode(encoding, errors="backslashreplace").decode(encoding)
+        except (LookupError, TypeError):
+            safe_description = description.encode("ascii", errors="backslashreplace").decode("ascii")
+        if safe_description == description:
+            return self._column(task)
+        display_task = copy(task)
+        display_task.description = safe_description
+        return self._column(display_task)
+
+
 class RichProgressBackend(ProgressBackend):
     """Rich Progress backend for terminal environments.
 
@@ -193,6 +252,8 @@ class RichProgressBackend(ProgressBackend):
     (Braille spinners, block-element bars) that cannot be encoded by
     limited console encodings such as GBK or Big5.  The spinner falls back
     to the ``"line"`` style (``|/-\\``) and the graphical bar is omitted.
+    Otherwise, columns follow the actual Rich console encoding on every render,
+    including background refreshes and changes to an already-created backend.
 
     Raises:
         RuntimeError: If ``rich`` is not installed. Callers should use
@@ -224,11 +285,17 @@ class RichProgressBackend(ProgressBackend):
             raise RuntimeError(_not_installed)
         if _TEXT_COLUMN_CLASS is None or _TIME_REMAINING_COLUMN_CLASS is None or _TRANSFER_SPEED_COLUMN_CLASS is None:
             raise RuntimeError(_not_installed)
+        if _GET_CONSOLE is None:
+            raise RuntimeError(_not_installed)
 
+        console = _GET_CONSOLE()
+        description_column = _EncodingAwareDescriptionColumn(
+            _TEXT_COLUMN_CLASS("[progress.description]{task.description}"), console=console
+        )
         if ascii_only:
             columns: list[Any] = [
                 _SPINNER_COLUMN_CLASS("line"),
-                _TEXT_COLUMN_CLASS("[progress.description]{task.description}"),
+                description_column,
                 _TEXT_COLUMN_CLASS("[progress.percentage]{task.percentage:>3.0f}%"),
                 _TEXT_COLUMN_CLASS("{task.completed}/{task.total}"),
                 _TRANSFER_SPEED_COLUMN_CLASS(),
@@ -236,16 +303,23 @@ class RichProgressBackend(ProgressBackend):
             ]
         else:
             columns = [
-                _SPINNER_COLUMN_CLASS(),
-                _TEXT_COLUMN_CLASS("[progress.description]{task.description}"),
-                _BAR_COLUMN_CLASS(),
+                _EncodingAwareColumn(_SPINNER_COLUMN_CLASS(), _SPINNER_COLUMN_CLASS("line"), console=console),
+                description_column,
+                _EncodingAwareColumn(_BAR_COLUMN_CLASS(), _TEXT_COLUMN_CLASS(""), console=console),
                 _TEXT_COLUMN_CLASS("[progress.percentage]{task.percentage:>3.0f}%"),
                 _TEXT_COLUMN_CLASS("{task.completed}/{task.total}"),
                 _TRANSFER_SPEED_COLUMN_CLASS(),
                 _TIME_REMAINING_COLUMN_CLASS(),
             ]
+        safe_columns = [
+            column
+            if isinstance(column, _EncodingAwareColumn)
+            else _EncodingAwareColumn(column, column, console=console)
+            for column in columns
+        ]
         self._progress = _PROGRESS_CLASS(
-            *columns,
+            *safe_columns,
+            console=console,
             transient=False,
             refresh_per_second=1,
         )
@@ -379,7 +453,7 @@ def create_progress(*, disable: bool = False) -> ProgressBackend:
         Jupyter+tqdm  → TqdmNotebookBackend     (native notebook widget)
         Jupyter-tqdm  → NullProgressBackend      (graceful degradation)
         Terminal+UTF8 → RichProgressBackend      (rich spinner + bar)
-        Terminal+GBK  → RichProgressBackend(ascii_only=True)  (ASCII spinner, no bar)
+        Terminal+GBK  → RichProgressBackend      (ASCII spinner, no bar)
 
     The Jupyter-without-tqdm path logs a one-time warning instead of raising
     ImportError, because progress display is a UX nicety, not a correctness
@@ -389,6 +463,8 @@ def create_progress(*, disable: bool = False) -> ProgressBackend:
     Rich's default spinner (Braille patterns) and bar (block elements), the
     factory automatically switches to an ASCII-safe layout so that Windows
     consoles with GBK / Big5 encodings do not crash with ``UnicodeEncodeError``.
+    The layout is checked again at render time so that redirected output does
+    not inherit the encoding decision of an earlier console.
     """
     if disable:
         return NullProgressBackend()
@@ -401,7 +477,7 @@ def create_progress(*, disable: bool = False) -> ProgressBackend:
         )
         return NullProgressBackend()
 
-    if ascii_only := not _can_render_unicode():
+    if not _can_render_unicode():
         logger.debug("Console encoding does not support Unicode progress characters — using ASCII-safe layout")
 
     if _PROGRESS_CLASS is None:
@@ -412,4 +488,4 @@ def create_progress(*, disable: bool = False) -> ProgressBackend:
         logger.debug("rich not installed — progress bars disabled. Install with: pip install sqlseed-cli")
         return NullProgressBackend()
 
-    return RichProgressBackend(ascii_only=ascii_only)
+    return RichProgressBackend()