Enhance impact analysis and configuration for vector persistence and API integration. Update main.spec to clarify data handling for ChromaDB, ensuring vector directories are excluded from packaging. Modify Text2SQLOrchestrator to unify question normalization for consistent SQL generation across languages. Introduce SchemaIndexer improvements for persistent vector storage and optimize embedding retrieval processes. Update documentation and comments for clarity on configuration changes and behavior adjustments.

main.spec

@@ -9,17 +9,26 @@ import sys
 _REPO_DIR = Path(os.getcwd()).resolve()
 
 # 根目录执行：pyinstaller --clean main.spec
-# 收集配置文件夹和数据文件
+#
+# ---------------------------------------------------------------------------
+# 向量「数据库文件」/ 业务数据 —— 明确不打入 onefile EXE
+# ---------------------------------------------------------------------------
+# 下列目录为运行时读写或外置分发的数据，禁止加入下方 ``datas``（勿取消注释）：
+#   - Schema 侧：环境变量 VECTOR_DB_PATH（默认如 ./data/embeddings/chroma）
+#   - Few-shot 侧：FEWSHOT_CHROMA_PATH（默认如 ./data/embeddings/chroma_fewshot）
+# 部署：将上述目录放在 exe 同目录旁，或通过 .env 指向可写绝对路径。
+# SchemaIndexer 默认使用 PersistentClient（VECTOR_DB_PATH）；仅 SCHEMA_INDEXER_EPHEMERAL=true 时为内存索引。
+# ---------------------------------------------------------------------------
+
+# 可选：仅当需要把 Schema JSON 等打进包时再取消注释（向量库目录仍不要加）
 datas = [
-    # 所有数据文件都不打包，从外部读取
     # ('.env', '.'),
     # ('data/schemas', 'data/schemas'),
-    # ('data/embeddings', 'data/embeddings'),
-    # ('data/experiences', 'data/experiences'),
+    # 勿打包 data/embeddings、data/experiences（向量库与样本数据外置）
 ]
 
-# ChromaDB 在 Windows 单文件 exe 下如缺少 native 动态库，可能在持久化访问时直接“硬退出”
-# 这里显式收集 chromadb 与 hnswlib（向量索引）的动态库/二进制依赖
+# Chroma **Python 包**在 Windows 单文件 exe 下如缺少 native 动态库，可能在初始化时直接退出
+# 这里收集的是 chromadb / hnswlib 的 **wheel 内 DLL**，不是用户磁盘上的 Chroma 持久化目录
 binaries = []
 try:
     binaries += collect_dynamic_libs("chromadb")
@@ -30,7 +39,7 @@ try:
 except Exception:
     pass
 
-# 某些 chromadb 版本会依赖包内数据文件（如 migrations/默认配置等），一并收集更稳妥
+# chromadb 包自带的非 Python 资源（如 migrations），非业务向量库文件
 try:
     datas += collect_data_files("chromadb")
 except Exception:
@@ -148,7 +157,7 @@ exe = EXE(
     pyz,
     a.scripts,
     a.binaries,
-    a.datas,  # 单文件模式：将数据文件打包进 exe
+    a.datas,  # 单文件：仅打包 spec 中 datas（chromadb 包资源等），不含业务向量持久化目录
     [],
     name='Backman_Text2SQL_Server',
     debug=False,