ai-g3sb-backman2.0/IMPACT_ANALYSIS.md

Impact Analysis Report — CJK 字面量校验（CASE 展示标签）

1. 改动概览

• 背景与目标：修复「CASE … THEN/ELSE 中使用中文状态标签」被 check_no_cjk_in_sql_string_literals 全文扫描误判为非法，导致合法查询反复重试仍失败的问题。规则本意是禁止在 WHERE/HAVING/ON/CASE 条件 中用中文与代码列比对。
• 涉及模块：backend/utils/validators.py（CJK 校验改为基于 sqlglot AST + 解析失败时回退全文扫描）、backend/agents/orchestrator.py（传入 dialect、T-SQL 硬性说明与注释对齐）、backend/config/prompts.py（2b 条款与校验语义一致）。
• 改动类型：缺陷修复（验证逻辑与提示词澄清）。

2. 方法级改动

位置	变更
check_no_cjk_in_sql_string_literals	解析成功时仅当 CJK 出现在 Where/Having/Join.on 或 Case 分支的 WHEN 条件（If.this）中报错；Case 的 THEN/ELSE 与纯 SELECT 展示字面量允许。支持 Literal 与 National（N'…'）。解析失败时回退旧版全文扫描（偏严）。
orchestrator._validate_sql	调用 check_no_cjk_in_sql_string_literals(sql, dialect=dialect)。

3. 调用方与影响范围

• 调用方：_validate_sql 内唯一调用点。
• 破坏性变更：否。行为变更：此前会失败的「仅 CASE/SELECT 含中文标签」现为通过；WHERE col = N'中文' 等仍失败。

4. 风险与回滚

• 风险级别：低。解析异常时仍走严格全文扫描。
• 回滚：还原 validators.py / 相关 prompt 与 orchestrator 片段。

回滚方式是否简单：是。

5. 验证与测试

• 已执行：脚本用例 — CASE … THEN '\u8d85\u989d' 通过；WHERE x = N'\u8d85\u989d' 失败。

6. 配置变更

• 无。

---

Impact Analysis Report — Prompt：无时间表述则不擅自加日期条件

1. 改动概览

• 背景与目标：强化 Text2SQL 提示词，避免用户未提任何时间时模型在 WHERE 中私自添加日期过滤；Few-shot 黄金适配时若当前问题比范例少时间条件，应去掉多余日期条件。
• 涉及模块：backend/config/prompts.py（SQL_GENERATOR_*、GOLDEN_SQL_ADAPT_*）、backend/agents/orchestrator.py（T-SQL 用户侧硬性要求追加一句）。
• 改动类型：配置/提示词优化（行为变更：模型被约束为少加臆测日期条件；非 API 签名变更）。

2. 方法级改动

位置	变更
SQL_GENERATOR_SYSTEM	新增硬性条款 1b（无时间表述则不加日期条件）；收紧第 2 条中「未给日期」与日期列的说明；推断指南增加前提行；黄金范例括号内补充「完全未提时间勿照抄日期」。
SQL_GENERATOR_USER	末尾一句指向 1b。
GOLDEN_SQL_ADAPT_SYSTEM	第 2 条补充：当前问题无时间要求时去掉标准答案中无关日期过滤。
orchestrator _generate_sql / _generate_sql_golden_adapt	T-SQL 硬性要求字符串追加与 1b 一致的一句提醒。

3. 调用方与影响范围

• 调用方：所有经 Text2SQLOrchestrator 走 SQL 生成的路径（含黄金适配分支）。
• 破坏性变更：否（仅 prompt 与 user 附加说明文本变化）。

4. 风险与回滚

• 风险级别：低。可能使「未说时间」类问题返回更宽结果集（符合预期）；若业务依赖模型以前「默认加近期」的隐式行为，需改为在用户问题或后端注入默认时间窗。
• 回滚：还原上述文件相关 diff。

回滚方式是否简单：是。

5. 验证与测试

• 建议手工：问题不含任何时间词 → 生成 SQL 应无新增日期列条件（除非 Schema/问题语义强制）；含「今天」→ 仍可用 GETDATE()。

6. 配置变更

• 无。

---

Impact Analysis Report — 会话上文注入 Text2SQL

1. 改动概览

• 背景与目标：在带 session_id 的 NL 对话中，将前几轮已落库的对话摘要注入选表、向量粗筛、SQL 生成与「无数据」说明，支持续问与指代消解。
• 涉及模块：api_server.py、backend/utils/dialog_context.py（新）、backend/utils/dialog_classifier.py、backend/agents/orchestrator.py。
• 改动类型：功能新增（向后兼容：无 session_id 或空历史时行为与原先一致）。

2. 方法级改动

位置	变更
LiteNlStore	无变更；仍由 _append_session_if_needed 在应答后写入。
_load_session_text2sql_context（api_server）	新增：读 get_messages，构造上文块，并判断上一轮是否为数据查询。
classify_dialog	新增可选关键字参数 last_turn_was_data_query；为 True 时在非寒暄/非元问题下将输入倾向判为 TEXT2SQL。
messages_to_text2sql_context 等	新工具：消息列表 → 可读摘要；解析 assistant JSON。
Text2SQLOrchestrator.generate	新增可选 dialog_context；粗筛/选表/续问 broker 优先/生成/无数据反馈使用该上文。
_generate_sql / _validate_sql	接收 dialog_context，Few-shot 检索问题与生成 user 提示含上文。

3. 调用方与影响范围

• 调用方：/g3sb/api/nl/chat、/g3sb/api/nl/chat/stream（仅当请求带有效 session_id 且会话内已有历史消息时生效）。
• CLI backend/main.py single_query：现传入 llm_client；当 DIALOG_INTENT_CLASSIFIER=rules 时与旧规则行为一致。
• 破坏性变更：否（新增可选参数与默认 False 的关键字参数）。

4. 风险与回滚

• 风险级别：中（依赖会话中 assistant 内容为合法 JSON；解析失败时上文退化为截断原文或空段）。
• 额外成本：带历史的请求 prompt 更长，token 与耗时可能上升。
• 回滚：回退本提交即可；无配置开关。

回滚方式是否简单：是。

5. 验证与测试

• 已执行：python -m py_compile 对改动文件语法检查。
• 建议手工：创建 session → 首轮数据查询 → 次轮「按上个月再查一遍」类续问，确认走 TEXT2SQL 且 SQL 与上文一致。

6. 配置变更

• 无。

---

Impact Analysis Report — 新增 OpenAI LLM Client（对话/JSON 输出）

1. 改动概览

• 背景与目标：补齐 backend/llm/openai_client.py，提供 OpenAI（或 OpenAI 兼容网关）调用封装，支持同步/异步 chat 与 chat_with_json，便于与既有 prompt/JSON 输出链路复用。
• 涉及模块：backend/llm/openai_client.py、.env（仅补充注释示例，不影响现有运行配置）。
• 改动类型：功能新增。

2. 方法级改动分析

位置	变更
OpenAIClient.chat	新增：基于 openai SDK 的 Chat Completions 调用封装，支持覆盖 temperature/max_tokens/top_p 等参数。
OpenAIClient.chat_with_json	新增：抽取/解析 JSON（兼容 markdown code fence）；解析失败时返回 {"_json_decode_failed": true, "raw_content": ...}。
create_openai_client	新增：从环境变量读取 OPENAI_API_KEY、可选 OPENAI_BASE_URL、OPENAI_MODEL/OPENAI_CHAT_MODEL。

3. 调用方与影响范围分析

• 调用方：当前仓库运行链路仍默认使用 DeepSeekClient；本次新增仅提供可选能力，未修改既有编排器/接口路由。
• 破坏性变更：否。

4. 风险与回滚

• 风险级别：低（新增模块，不改变既有默认路径）。
• 回滚：删除新增文件与对应文档/注释即可。

回滚方式是否简单：是。

5. 验证与测试

• 已执行：python -m py_compile backend/llm/openai_client.py。

6. 配置变更

• .env：补充 OPENAI_MODEL/OPENAI_CHAT_MODEL 注释示例（不修改现有真实配置）。

---

Impact Analysis Report — DeepSeek/OpenAI 双模型切换（LLM_SERVICE_CODE）

1. 改动概览

• 背景与目标：支持在 DeepSeek 与 OpenAI（或兼容网关）之间切换 LLM 调用来源，便于在不同环境/配额下切换推理服务。
• 涉及模块：backend/llm/router.py（新）、backend/agents/orchestrator.py、backend/main.py、api_server.py、.env（新增开关）。
• 改动类型：功能增强（可配置路由）。

2. 方法级改动分析

位置	变更
backend/llm/router.py	新增：resolve_llm_service_code + create_llm_client，按 LLM_SERVICE_CODE 或 Key 存在性创建 LLM Client。
Text2SQLOrchestrator.__init__	新增可选 llm_client 参数；若传入则作为 self.deepseek 使用（保留属性名避免大范围改动）。
backend/main.py	setup_environment 增加 LLM_SERVICE_CODE 校验；create_orchestrator 通过 router 创建 LLM Client。
api_server.py	错误提示文案更新；编排器初始化保持通过 create_orchestrator 完成。

3. 调用方与影响范围分析

• 调用方：CLI（backend/main.py）与 API（api_server.py）初始化编排器路径。
• 行为变化：
  • LLM_SERVICE_CODE=openai：使用 OPENAI_* 做 LLM 调用（意图分类 / 归一 / 选表 / 生成 / 说明等）。
  • LLM_SERVICE_CODE=deepseek 或未设置但存在 DEEPSEEK_API_KEY：仍默认 DeepSeek（与历史一致）。
• 破坏性变更：否（对外 API 入参/出参不变；仅初始化与内部客户端来源可切换）。

4. 风险与回滚

• 风险级别：中（不同模型对 JSON 严格性/输出格式偏好不同，可能影响 chat_with_json 的解析成功率与稳定性；失败时仍会返回 _json_decode_failed 供上游处理）。
• 回滚：将 LLM_SERVICE_CODE 切回 deepseek 或回退相关文件改动。

回滚方式是否简单：是。

5. 验证与测试

• 已执行：python -m py_compile 覆盖 backend/llm/router.py、backend/agents/orchestrator.py、backend/main.py、api_server.py。

6. 配置变更

配置项	含义	取值
LLM_SERVICE_CODE	选择 LLM 路由	openai / deepseek（留空自动按 Key 选择，优先 deepseek）

---

Impact Analysis Report — 适配前端参数（lang_code / model）

1. 改动概览

• 背景与目标：前端请求会携带 lang_code（zh/tc/en）与 model（模型名覆盖）；后端需接收并在对话分支/LLM 调用侧生效。
• 涉及模块：api_server.py。
• 改动类型：兼容性增强。

2. 方法级改动分析

位置	变更
NLChatRequest	新增 model 字段；保留 lang_code（规范化为 zh/tc/en/auto）。
nl_chat / _chat_stream_events	对话分支：空输入/默认引导文案按 lang_code 返回（中/繁/英）。
_maybe_override_orch_llm（新）	若请求带 service_code/model，临时覆盖 orchestrator.deepseek 为按请求创建的 LLM client；使用锁避免并发串改。
_run_generate	增加 request 参数，用于按请求覆盖 LLM client 后再生成。

3. 调用方与影响范围分析

• 调用方：/g3sb/api/nl/chat、/g3sb/api/nl/chat/stream。
• 破坏性变更：否（仅新增可选请求字段与内部适配；未提供时行为保持不变）。

4. 风险与回滚

• 风险级别：中（带 model/service_code 的请求会串行化执行 LLM 调用，避免并发污染；在高并发时可能降低吞吐）。
• 回滚：回退 api_server.py 的按请求覆盖逻辑即可。

回滚方式是否简单：是。

5. 验证与测试

• 已执行：python -m py_compile api_server.py。

Impact Analysis Report — 方案A：新话题禁用 dialog_context（防上下文污染）

1. 改动概览

• 背景与目标：同一会话内出现多个不同话题时，历史摘要（含上轮 SQL）注入 Text2SQL 易造成上下文污染，导致选表/条件串话。本次引入“续问判定”规则：仅在疑似续问时注入少量上文；新话题默认不注入上文。
• 涉及模块：api_server.py、backend/utils/dialog_context.py。
• 改动类型：缺陷修复 / 行为优化（仅影响带 session_id 且存在历史消息的请求）。

2. 方法级改动分析

位置	变更
backend/utils/dialog_context.py is_likely_follow_up	新增：基于用户文本的轻量续问判定（关键字/短句规则），用于决定是否需要注入上文。
api_server.py _load_session_text2sql_context	调整：新增 user_text 入参；根据 is_likely_follow_up(user_text) 选择 max_pairs=2 或 0，并据此构造 dialog_context。
api_server.py 两个入口	调整：/g3sb/api/nl/chat 与 /g3sb/api/nl/chat/stream 调用 _load_session_text2sql_context(request, text)。

3. 调用方与影响范围分析

• 调用方：/g3sb/api/nl/chat、/g3sb/api/nl/chat/stream（请求带 session_id 且历史不为空时生效）。
• 行为变化：
  • 新话题（非续问）：dialog_context 变为空（不再携带历史摘要），降低串话风险。
  • 续问：仅携带最近 2 轮（原默认最多 8 轮），降低旧话题回流概率。
• 破坏性变更：否（对外 API 入参/出参未变；仅内部上下文组装策略变化）。

4. 风险与回滚

• 风险级别：中（可能把少量“隐式续问”误判为新话题，导致指代消解能力下降；但能显著降低跨话题污染）。
• 回滚：回退本次提交（或将 max_pairs 固定恢复为 8 / 去掉续问判定）。

回滚方式是否简单：是。

5. 验证与测试

• 建议手工：
  • 同一 session：话题A生成 SQL → 话题B（无续问词）应不再引用 A 的表/条件。
  • 同一 session：首轮查询 → 次轮“再/按上面/沿用口径”续问，应仍能沿用上轮 SQL 的业务口径。

6. 配置变更

• 无。

Impact Analysis Report — 库探针追问与交付分支（追加）

1. 改动概览

• 目标：对齐库探针语义：0 无行时返回 SQL + 问题分析 + 固定追问引导重生成；1 有行时由 LLM 生成简短交付说明并返回 SQL；-1 失败时明确文案并走既有重试。
• 涉及模块：backend/agents/orchestrator.py、backend/llm/deepseek_client.py、backend/config/prompts.py、api_server.py（DataQueryResult 字段）、backend/utils/dialog_context.py（摘要）。

2. 破坏性变更

• 否（API 新增可选字段；未配置 database_url 时行为与原先一致）。

3. 风险

• 低～中：探针为 1 时增加一次 LLM 调用（延迟与 token）；失败时降级为仅返回 SQL。

4. 验证

• python -m py_compile 覆盖改动文件。

---

Impact Analysis Report — Few-shot 写入 Chroma（追加）

1. 改动概览

• 目标：将 all_samples.jsonl 写入 Chroma 持久化向量库；FEWSHOT_USE_CHROMA=true 时 FewShotSelector 从 Chroma 检索，否则仍用内存 + .npy 缓存。
• 新增：backend/utils/fewshot_chroma_store.py、scripts/build_fewshot_chroma_index.py；.env 增加注释说明；FewShotSelector 扩展参数与分支逻辑。

2. 破坏性变更

• 否（默认 FEWSHOT_USE_CHROMA 未开启时行为不变）。

3. 风险

• 中：Chroma metadata 对单字段长度有限制，超长 SQL/说明在入库时截断；换 Embedding 模型后应 --force 重建索引。

4. 验证

• python -m py_compile 已通过相关文件。

追加（Chroma 优先、JSONL 可选）：FEWSHOT_USE_CHROMA=true 且未设置 FEWSHOT_DATA_PATH 时，编排器默认不再读 JSONL；FewShotSelector 支持无文件 + Chroma 检索；get_stats / get_tagged_examples 在无内存样本时从 Chroma 全量导出统计。

追加（Embedding 默认远程）：移除对 data/models/Qwen3-Embedding-0.6B 的默认依赖；USE_LOCAL_EMBEDDING 默认视为 false；get_embedder / setup_environment / EMBEDDING_MODEL_PATH 与文档对齐为「远程 OpenAI 兼容等优先，本地仅显式开启」。

---

Impact Analysis Report — Workbuddy Markdown → JSONL（追加）

1. 改动概览

• 目标：将 data/常问问题对应SQL_50个问题知识库_Workbuddy生成.md 转为与 data/experiences/all_samples.jsonl 同结构的 JSONL，并保证每条含 question_en（英文题干）。
• 新增：scripts/md_workbuddy_to_jsonl.py；产出 data/experiences/workbuddy_50_questions.jsonl（50 行）。
• 改动类型：数据与脚本（可重复生成）。

2. 方法级说明

• 解析 Markdown 中 ## Qn 节：### 问题（中英分行）、全部 ```sql 块（去重拼接）、### SQL执行结果 / 内联结果、### SQL理由、### SQL准确度评分。
• 与 all_samples.jsonl 按 qid 合并 schema_info、tags、difficulty；正文覆盖 question_zh、question_en、sql、explanation、rating、result_note。
• 写出 JSONL 时字段顺序固定为：question_zh 后紧跟 question_en（便于在极长单行里肉眼看到英文题干）。
• Q50：Markdown 仅有中文问题；脚本补充 question_en：List all client trade records for today.

3. 调用方与破坏性变更

• 调用方：无运行时自动引用；需手工执行 python scripts/md_workbuddy_to_jsonl.py 或下游自行读 JSONL。
• 破坏性变更：否。

4. 风险与回滚

• 风险：低（生成物可被版本管理；schema_info 与含多段 SQL 的题目可能不完全一致，仍以 all_samples 为基线）。
• 回滚：删除脚本与 JSONL，或从 Git 回退。

回滚方式是否简单：是。

5. 验证

• 已执行：python scripts/md_workbuddy_to_jsonl.py；校验 50 行且 question_en 均非空。

6. 配置变更

• 无。

---

Impact Analysis Report — 对话意图 hybrid + LLM（追加）

1. 改动概览

• 背景与目标：纯规则在「上一轮为数据查询」时把「结果不对」等反馈误判为 TEXT2SQL；改为默认 hybrid：明显查数词/寒暄/元问题仍走规则，其余由 LLM 输出 JSON 判定 text2sql / conversation。
• 涉及模块：backend/utils/dialog_classifier.py、backend/config/prompts.py（DIALOG_INTENT_CLASSIFIER_*）、api_server.py、backend/main.py。
• 改动类型：功能调整（默认多一次小 LLM 调用；可配置关闭）。

2. 方法级改动

位置	变更
classify_dialog	新增可选参数 dialog_context、llm_client；引入 _classify_dialog_rules、_classify_dialog_llm；读环境变量 DIALOG_INTENT_CLASSIFIER。
api_server 流式/非流式 NL	在分类前 get_orchestrator()，用 asyncio.to_thread(classify_dialog, ..., llm_client=orch.deepseek) 避免阻塞事件循环。
single_query	classify_dialog(question, llm_client=orchestrator.deepseek) 与 API 对齐。

3. 调用方与影响范围

• 调用方：/g3sb/api/nl/chat、/g3sb/api/nl/chat/stream、single_query。
• 破坏性变更：否；DIALOG_INTENT_CLASSIFIER=rules 时与原先规则路径一致（无 LLM 意图调用）。

4. 风险与回滚

• 风险级别：中（每轮非「快速命中」类输入增加一次短 LLM 调用：延迟与费用；JSON 异常时回退规则）。
• 回滚：设 DIALOG_INTENT_CLASSIFIER=rules 或回退代码提交。

回滚方式是否简单：是。

5. 验证与测试

• 建议手工：hybrid 下首轮查数 → 次轮「这个结果不正确呀」应判为 conversation 并返回引导文案，不跑选表/SQL 链路。

6. 配置变更

配置项	含义	默认
DIALOG_INTENT_CLASSIFIER	hybrid：规则快速路径 + LLM；rules：仅规则	hybrid（未设置时按 hybrid 处理）

---

Impact Analysis — 移除本地 Embedding（仅远程 API）

1. 改动概览

• 背景与目标：不再维护本地 HuggingFace / PyTorch 推理路径；Embedding 统一为 OpenAI 兼容远程 /v1/embeddings。
• 涉及模块：backend/utils/embedding.py、backend/main.py、backend/agents/orchestrator.py、backend/utils/fewshot_selector.py、backend/config/settings.py、api_server.py、scripts/build_fewshot_chroma_index.py、pyproject.toml、requirements.txt、main.spec、README.md、.env 注释。
• 改动类型：功能删减 / 依赖精简。

2. 方法级改动

位置	变更
Qwen3Embedding（原）	删除；本地 transformers+torch 编码路径移除。
get_embedder	仅构造 OpenAICompatibleRemoteEmbedding；前两个位置参数废弃保留以兼容旧调用。
clear_embedder	仅 gc.collect()，不再触碰 CUDA。
Text2SQLOrchestrator.__init__	移除 embedding_model_path；FewShotSelector 不再传模型路径。
FewShotSelector.__init__	移除 embedding_model_path。
setup_environment	删除 USE_LOCAL_EMBEDDING / EMBEDDING_MODEL_PATH 分支。

3. 调用方与影响范围

• 调用方：所有原 get_embedder(path) 仍可运行（路径被忽略）；Text2SQLOrchestrator(..., embedding_model_path=...) 需改为不传该参数（已改仓库内引用）。
• 破坏性变更：是——不再支持 USE_LOCAL_EMBEDDING=true 与本地模型目录；pyproject.toml / requirements.txt 不再声明 torch/transformers/sentencepiece/accelerate/safetensors（若 camel-ai[all] 等仍带入部分传递依赖，以实际 lock 为准）。

4. 风险与回滚

• 风险级别：中（仅使用本地 Embedding 的部署将失效；需改为远程 Key 与模型名）。
• 回滚：回退提交并恢复依赖与 embedding.py 历史版本。

回滚方式是否简单：是（单提交回退）。

5. 验证与测试

• 建议：python -m py_compile 对改动 .py；在已配置 OPENAI_* 或 MODELSCOPE_* 的环境下跑一次 Schema 向量构建或 Few-shot 检索。

6. 配置变更

移除/失效项	说明
USE_LOCAL_EMBEDDING、EMBEDDING_MODEL_PATH	代码不再读取；.env 中可删去以免误解。
CLI --embedding-model	已删除。

---

Impact Analysis Report — main.spec：向量持久化目录不落包（追加）

1. 改动概览

• 背景与目标：在 PyInstaller 配置中明确约定「业务侧 Chroma/向量持久化目录」不加入 datas，避免误将 data/embeddings 等打入 onefile；实际打包行为与此前一致（datas 中本未包含上述目录）。
• 涉及模块：main.spec。
• 改动类型：配置说明 / 文档化。

2. 方法级改动

位置	变更
main.spec 顶部注释与 datas	写明 VECTOR_DB_PATH、FEWSHOT_CHROMA_PATH 对应目录外置；区分 chromadb wheel 依赖与用户向量库文件；EXE 处注释澄清 a.datas 含义。

3. 调用方与影响范围

• 调用方：仅 pyinstaller main.spec 打包流程；运行时仍依赖环境变量或旁路目录提供向量库（与代码逻辑无变更）。
• 破坏性变更：否。

4. 风险与回滚

• 风险级别：低。
• 回滚：还原 main.spec 对应注释块。

回滚方式是否简单：是。

5. 验证与测试

• 打包前确认 datas 无 data/embeddings 等元组；打包后 exe 旁按需放置向量目录并配置 .env。

---

Impact Analysis Report — 前端默认 NL API 地址（追加）

1. 改动概览

• 目标：前端开发与 UAT 打包默认后端 origin 改为 http://0.0.0.0:8041；同 host 解析时默认端口改为 8041。
• 涉及模块：ai-g3sb-backman-web/vite.config.ts（VITE_DEV_API_TARGET 默认值）、ai-g3sb-backman-web/src/api/packagedOrigin.ts、ai-g3sb-backman-web/src/api/config.ts；src/locales/{zh,tw,en}.ts 中管理端 API 占位示例同步。
• 改动类型：配置默认值变更。

2. 调用方与破坏性变更

• 调用方：Vite 开发代理 /g3sb；非 test 构建注入的 window.__BACKMAN_API_ORIGIN__ 与 apiBase() 默认打包 origin。
• 破坏性变更：否（仍可通过环境变量 VITE_DEV_API_TARGET、VITE_PACKAGED_API_ORIGIN、VITE_PACKAGED_API_PORT 覆盖）。

3. 风险与回滚

• 风险级别：低。说明：浏览器直连 0.0.0.0 在部分环境下可能不如 127.0.0.1 可靠；若遇连接问题可改用 VITE_* 覆盖为实际可访问地址。
• 回滚：还原上述三处默认值或设置环境变量覆盖。

回滚方式是否简单：是。

4. 配置变更

项	说明
VITE_DEV_API_TARGET（可选）	未设置时默认 http://0.0.0.0:8041。
PACKAGED_API_ORIGIN / VITE_PACKAGED_API_ORIGIN	代码内默认改为 http://0.0.0.0:8041。
VITE_PACKAGED_API_PORT（可选）	same-host/auto 时未设置则默认 8041。

---

Impact Analysis Report — SchemaIndexer 持久化 Chroma（追加）

1. 改动概览

• 背景与目标：原先 SchemaIndexer 固定使用 EphemeralClient，进程内集合恒为空，每次请求粗筛都会全量计算约 2500+ 张表的 embedding；用户已在 data/embeddings/chroma 等目录落盘向量库，应直接复用。
• 涉及模块：backend/schema/indexer.py、backend/agents/orchestrator.py（日志与 force_rebuild）、backend/utils/fewshot_chroma_store.py（注释）、main.spec（打包说明注释）。
• 改动类型：缺陷修复 / 行为优化（性能与成本）。

2. 方法级改动

位置	变更
SchemaIndexer.__init__	默认 chromadb.PersistentClient(path=persist_dir)，创建目录；SCHEMA_INDEXER_EPHEMERAL=true 或 use_ephemeral=True 时仍为 EphemeralClient。默认 persist_dir 与 VECTOR_DB_PATH 对齐为 ./data/embeddings/chroma。
SchemaIndexer.get_statistics	chroma_mode 区分 persistent / memory。
Text2SQLOrchestrator._coarse_filter	每次粗筛前调用 SchemaIndexer.ensure_index_for_schema：索引条数与当前 Schema 表数一致则跳过向量化；空库则构建；不一致则 force_rebuild 重建。
SchemaIndexer.ensure_index_for_schema（新）	对比 collection.count() 与 len(schema_manager.get_tables())，避免无意义重复向量化，并在 Schema 增删表后自动重载索引。

3. 调用方与影响范围

• 调用方：Text2SQLOrchestrator._get_vector_index() 传入的 persist_dir 仍为 vector_db_path / 环境变量 VECTOR_DB_PATH；向量粗筛路径经 ensure_index_for_schema。
• 破坏性变更：否。若依赖「每次进程冷启动强制空向量库」的测试，需设置 SCHEMA_INDEXER_EPHEMERAL=true。

4. 风险与回滚

• 风险级别：低。说明：Embedding 模型或维度变更时，旧持久化向量与当前 encoder 不一致可能导致检索质量下降，需删除目录或调用带 force_rebuild 的构建逻辑重建。
• 回滚：还原 indexer.py 相关提交或设置 SCHEMA_INDEXER_EPHEMERAL=true。

回滚方式是否简单：是。

5. 配置变更

项	说明
VECTOR_DB_PATH	既有；默认 ./data/embeddings/chroma，现为 Schema Chroma 真实持久化根路径。
SCHEMA_INDEXER_EPHEMERAL（可选）	设为 true/1/yes 时使用内存 Chroma（与旧行为一致）。

---

Impact Analysis Report — 中英文问句归一以提升 SQL 一致性（追加）

1. 改动概览

• 背景与目标：同一业务语义分别用中文、英文提问时，原先仅对「纯英文」问句做英译中，中文问句原样进入检索/生成，导致与英文路径的表述不一致，向量粗筛与 SQL 可能分叉。
• 涉及模块：backend/config/prompts.py（归一提示词 + SQL_GENERATOR 约束）、backend/llm/deepseek_client.py、backend/agents/orchestrator.py、backend/main.py（CLI 帮助文案）。
• 改动类型：行为优化；默认仍受 TRANSLATE_EN_TO_ZH / --no-translate-en 控制。

2. 方法级改动

位置	变更
DeepSeekClient.normalize_nl_question_for_text2sql	新增：temperature=0 下将中/英问句归一为一句中文。
DeepSeekClient.translate_nl_question_to_zh	改为委托上述方法（兼容旧名）。
Text2SQLOrchestrator.generate	当 translate_english_to_zh 为 True 时，对所有非空问句调用归一（不再仅限 looks_like_english_only）。
SQL_GENERATOR_SYSTEM	新增硬性约束第 6 条：中英文同义时 SQL 逻辑须一致。

3. 调用方与破坏性变更

• 调用方：所有经 generate() 的 Text2SQL 请求（含 api_server 默认 TRANSLATE_EN_TO_ZH 开启时）。
• 破坏性变更：否。关闭归一：TRANSLATE_EN_TO_ZH=false 或 --no-translate-en / Args.no_translate_en，行为与改动前「中文不归一、英文仍可不译」一致。

4. 风险与回滚

• 风险级别：低～中。每次成功归一增加一次 LLM 调用（延迟与 token）；归一失败时回退原文（与旧失败策略一致）。
• 回滚：关闭环境变量或还原相关文件。

回滚方式是否简单：是。

5. 配置变更

项	说明
TRANSLATE_EN_TO_ZH	语义扩展为「是否做问句归一中文」；false 关闭额外 LLM 归一步骤。

---

Impact Analysis Report — Few-shot Chroma 默认读盘（追加）

1. 改动概览

• 问题：FEWSHOT_USE_CHROMA=true 时 FewShotChromaStore 仍默认 EphemeralClient，进程内 count 恒为 0，每次启动从 JSONL 重算 embedding，忽略已灌库的 data/embeddings/chroma_fewshot。
• 模块：backend/utils/fewshot_chroma_store.py。
• 类型：缺陷修复。

2. 行为变更

项	说明
默认	persist_to_disk=None 时默认使用 PersistentClient（FEWSHOT_CHROMA_PATH 或 ./data/embeddings/chroma_fewshot）。
退出	FEWSHOT_CHROMA_EPHEMERAL=true 或构造参数 persist_to_disk=False 时仍为内存 Chroma。

3. 破坏性变更

• 否。灌库脚本显式 persist_to_disk=True 不变。

4. 配置

| FEWSHOT_CHROMA_EPHEMERAL | 可选；true 时与旧版「仅内存」行为一致。 |

---

Impact Analysis Report — /g3sb/api/nl/chat/stream 分片 SSE（追加）

1. 改动概览

• 背景与目标：前端 chatStore 按多次 { stage, stream_kind, content } 累加 chatText / sqlGenHtml；原先后端在 chat / sql_gen 阶段各只发一条大包，网络侧无渐进感。
• 涉及模块：api_server.py。
• 改动类型：行为优化（SSE 事件形态不变，仅增加条数）。

2. 方法级改动

位置	变更
_sse_stream_text_chunks	新增：按字符窗口（默认 64，可用 SSE_STREAM_CHUNK_CHARS 覆盖）拆成多段 SSE；段间 asyncio.sleep(0) 让出事件循环。
_chat_stream_events	chat / sql_gen 正文改为 async for 分片 yield。

3. 破坏性变更

• 否（结束包 code/msg/data 仍与原先一致）。

4. 配置变更

项	说明
SSE_STREAM_CHUNK_CHARS	可选；每段 SSE 的 content 最大字符数，默认 64。

---

Impact Analysis Report — API 日志落盘与可观测性（追加）

1. 改动概览

• 背景与目标：终端日志偏少，难以排查 Text2SQL 全链路问题；需将更细粒度的日志写入仓库 logs/，且每次进程启动只保留一个 .log 文件。
• 涉及模块：api_server.py、backend/utils/repo_logging.py（新）、backend/agents/orchestrator.py、backend/schema/indexer.py、backend/utils/dialog_classifier.py。
• 改动类型：可观测性增强（行为对业务结果无影响）。

2. 方法级改动

位置	变更
configure_text2sql_api_logging	新建：清空 logs/*.log，创建 logs/text2sql_api.log（覆盖写）；root 双 Handler（控制台简短格式 + 文件含 filename/lineno/funcName）；关闭 Chroma/posthog 遥测 logger；httpx/httpcore 降为 WARNING。
api_server 导入段	在 from main import … 之前调用上述配置；移除 basicConfig；uvicorn.run(..., log_config=None) 避免覆盖 root（勿用 False，否则会走 fileConfig 崩溃），并清空 uvicorn 自带 handler 改为 propagate。
_run_generate / nl_chat / _chat_stream_events	增加请求维度、对话上文长度、流式结束时的 valid/attempts/tables/SQL 摘要等 INFO 日志。
Text2SQLOrchestrator	向量粗筛输出表名+分数列表；选表输出 reasoning 预览；few-shot 注入 qid 与问题预览；生成 SQL 全文（超长截断至约 12k 字符）；_validate_sql 返回前汇总 valid/errors/warnings/探针。
SchemaIndexer.search	检索结果由 DEBUG 改为 INFO，输出命中数与 top 表+分。
classify_dialog 规则/hybrid 快路径	DEBUG 改为 INFO，附用户输入预览；LLM 分支补充 reply 预览。

3. 调用方与影响范围

• 调用方：仅通过 python api_server.py（或等价导入 api_server）启动 API 时生效；backend/main.py CLI 仍使用自身 basicConfig，不落盘到本 logs/text2sql_api.log（未改 CLI）。
• 破坏性变更：否。

4. 风险与回滚

• 风险级别：低。日志文件可能含用户查询片段与 SQL，需注意磁盘与隐私（内网演示场景可接受）。
• 回滚：删除 repo_logging 调用与相关增强日志，恢复 basicConfig 与默认 uvicorn.run 即可。

回滚方式是否简单：是。

5. 验证与测试

• 建议：python -m py_compile api_server.py backend/utils/repo_logging.py；启动 python api_server.py 后确认生成 logs/text2sql_api.log 且重启后仅保留该文件。

6. 配置变更

• 无新增环境变量；日志路径固定为仓库根下 logs/text2sql_api.log。

---

Impact Analysis Report — Chroma Few-shot 黄金 SQL 条件适配（追加）

1. 改动概览

• 背景与目标：data/embeddings/chroma_fewshot 中存储的问答-SQL 视为已校验正确答案；当向量检索与当前问题足够相似时，不再仅作「风格示例」，而是以该 SQL 为骨架，仅让 LLM 调整 WHERE/HAVING 等与用户问题相关的特殊条件。
• 涉及模块：backend/config/prompts.py（GOLDEN_SQL_ADAPT_*）、backend/utils/fewshot_selector.py（select_best_with_score、is_chroma_backend）、backend/agents/orchestrator.py（_generate_sql_golden_adapt、_generate_sql 分支）、api_server.py（响应中可选 fewshot_golden）。
• 改动类型：生成策略增强（默认开启，可用环境变量关闭或调阈值）。

2. 方法级改动

位置	变更
FewShotSelector	新增 _passes_filters、select_best_with_score；is_chroma_backend 属性。
Text2SQLOrchestrator._generate_sql	在 Chroma 且满足阈值时调用 _generate_sql_golden_adapt 并设置 _last_fewshot_golden；否则沿用原 few-shot 注入 + 全量生成。
_generate_sql_golden_adapt	使用 GOLDEN_SQL_ADAPT_SYSTEM/USER，强调保留 JOIN/SELECT 结构、仅改条件。
generate	metadata 增加 fewshot_golden_reuse、fewshot_golden_qid、fewshot_golden_score；失败路径亦回传（若曾走黄金分支）。
_nl_dict_from_generation	若存在黄金复用，增加 fewshot_golden 字段供前端展示/调试。

3. 破坏性变更

• 否。未命中阈值时行为与原先「多示例风格参考」一致。

4. 配置变更

环境变量	含义	默认
FEWSHOT_GOLDEN_REUSE	是否启用黄金 SQL 条件适配	true
FEWSHOT_GOLDEN_ONLY_CHROMA	是否仅在 Chroma 后端启用（与 chroma_fewshot 策略一致）	true
FEWSHOT_GOLDEN_MIN_SCORE	最低相似度（1-距离，约等于余弦相似度）	0.88
FEWSHOT_GOLDEN_SQL_PROMPT_MAX	写入提示词的标准答案 SQL 最大字符数	16000

5. 风险与回滚

• 风险：阈值过低可能把不太相似的问题强行套在同一 SQL 上；过高则很少触发黄金分支。
• 回滚：设 FEWSHOT_GOLDEN_REUSE=false 或回退相关提交。

回滚方式是否简单：是。

---

Impact Analysis Report — 流式 SSE sql_gen 分片与节流

1. 改动概览

• 背景与目标：前端约定每条 SSE 为 data: {"stage":"sql_gen","stream_kind":"content","content":"..."}；服务端需按 LLM 原生流式 delta 透传（默认不二次切分），并支持可选分片间隔。
• 涉及模块：api_server.py（/g3sb/api/nl/chat/stream、_iter_sql_gen_content_pieces、_sse_stream_text_chunks）。
• 改动类型：行为调整（默认分片粒度为 delta：不做二次切分；如确需更细粒度可配置 char）。

2. 方法级改动

位置	变更
NLChatRequest	新增可选 sql_stream_granularity（sqlStreamGranularity）；明确 streaming_throttle 为相邻 content 间隔毫秒。
_iter_sql_gen_content_pieces	支持传入 mode；未设置时 SSE_SQL_GEN_SPLIT 默认 delta（不切分）。
_chat_stream_events	sql_gen 循环按粒度拆分后对每条 data 可选 asyncio.sleep(throttle)；寒暄分支 _sse_stream_text_chunks 支持相同节流。

3. 调用方与影响范围

• 调用方：仅 SSE 流式客户端；非流式 /g3sb/api/nl/chat 不变。
• 破坏性变更：否。未传新字段时：粒度由 SSE_SQL_GEN_SPLIT 决定（默认 delta，事件条数与 LLM 原生一致）；若需更细粒度可设 SSE_SQL_GEN_SPLIT=char 或请求体 sqlStreamGranularity: "char"。

4. 配置变更

环境变量	含义	默认
SSE_SQL_GEN_SPLIT	delta：与 LLM 增量一致；char：逐 Unicode 标量多条 SSE	delta（未设置 env 时由代码默认）

5. 风险与回滚

• 风险级别：低。char 模式下 SSE 条数增加，带宽与前端拼接次数上升。
• 回滚：设 SSE_SQL_GEN_SPLIT=delta 或请求传 sqlStreamGranularity: "delta"（回到默认：不切分）。

回滚方式是否简单：是。

6. 验证与测试

• 已执行：python -m py_compile api_server.py。

---

Impact Analysis Report — API 回包增加 data.sql / data.explanation 便捷字段

1. 改动概览

• 背景与目标：前端需要在响应 data 内直接读取 {"sql":"..."}（SQL 可含 -- 注释且无 ``` 围栏），并单独读取自然语言解释字段。
• 涉及模块：api_server.py（NLChatSuccessData、_nl_dict_from_generation）。
• 改动类型：向后兼容的字段补充（不移除/不改名原有字段）。

2. 方法级改动

位置	变更
NLChatSuccessData	新增可选字段 sql、explanation（便捷读取）。
_nl_dict_from_generation	在原有 intent/branch_result 之外补充 payload["sql"] 与 payload["explanation"]；explanation 优先取 sql_delivery_message，否则回退到 sql_explain。

3. 调用方与影响范围

• 调用方：/g3sb/api/nl/chat 与 /g3sb/api/nl/chat/stream 的结束包 data。
• 破坏性变更：否（仅新增字段；原 branch_result.sql 等保持不变）。

4. 风险与回滚

• 风险级别：低（新增字段）。
• 回滚：回退本改动提交即可。

回滚方式是否简单：是。

5. 验证与测试

• 已执行：python -m py_compile api_server.py。

---

Impact Analysis Report — SSE 流式 SQL 说明与可选 <data>{"sql":...}</data> 片段（可开关）

1. 改动概览

• 背景与目标：流式 /g3sb/api/nl/chat/stream 需要给客户端展示 SQL（LLM 原生 delta）并在必要时提供结构化 SQL。由于当前前端会直接拼接展示 delta 且保留 <data>，因此结构化 <data> 片段默认不补发，避免同一次流里出现两段可见 SQL；如有需要可通过环境变量开关启用。
• 涉及模块：api_server.py（_chat_stream_events）。
• 改动类型：向后兼容增强（流式末尾追加内容；并过滤 LLM 可能自行输出的 <data>...</data>，避免前端出现重复 SQL/重复结构化片段）。

2. 方法级改动分析

位置	变更
_chat_stream_events	透传 LLM 的 sql_gen delta 用于展示；过滤 LLM 自吐的 <data>...</data> 段。流结束时结构化 <data>{"sql":...}</data> 默认不补发，仅在 SSE_APPEND_SQL_DATA_TAG=true 时启用补发，避免前端拼接展示时出现重复 SQL。

3. 调用方与影响范围分析

• 调用方：前端 SSE 消费逻辑（stage="sql_gen"、stream_kind="content"）。
• 影响：
  • 展示：若前端直接展示原始流文本，将额外看到「SQL 说明」与 <data>...</data>；但通常前端会对 <data>...</data> 做隐藏/抽取，不影响页面展示。
  • 解析：前端可在流末尾稳定抽取 SQL（而不依赖临时拼接或额外请求非流式接口）。
• 破坏性变更：否（仅追加；不更改原有字段与 SSE 事件结构）。

4. 风险与回滚

• 风险级别：低（开关打开时，若前端未过滤 <data>，可能展示出标签；默认关闭避免此问题）。
• 回滚：默认即不补发；如需恢复补发仅需设置 SSE_APPEND_SQL_DATA_TAG=true，或回退代码提交。

回滚方式是否简单：是。

5. 验证与测试

• 已验证：python -m py_compile api_server.py；默认不再补发 <data>{"sql":...}</data>，且不会透传 LLM 自行生成的 <data>...</data> 段；需要结构化输出时可设置 SSE_APPEND_SQL_DATA_TAG=true 验证补发行为。

---

Impact Analysis Report — api_server 精简未使用请求/查询参数

1. 改动概览

• 背景与目标：删除 api_server.py 中未被业务逻辑使用的请求字段与路由形参，减少噪音；stub 接口不再声明从不读取的请求体模型。
• 涉及模块：api_server.py。
• 改动类型：重构（对外行为基本不变）。

2. 方法级改动

位置	变更
NLChatRequest	移除字段 taskId（仓库内无读取）。
SqlExecuteBody	删除模型；POST /g3sb/api/nl/sql/execute 无请求体形参（仍返回 501）。
POST /g3sb/api/nl/operation-logs	移除未使用的 Body 形参（仍返回 200）。
GET /g3sb/api/nl/operation-logs	仅保留 limit、offset；其余查询参数从签名中移除。
GET /g3sb/api/nl/knowledge-docs/uploads	移除未使用的 doc_type，保留 limit、offset。
lifespan、全局异常处理	未使用的 app/_req 形参改为 _app / _（语义不变）。

3. 调用方与影响范围

• 调用方：ai-g3sb-backman-web 的 nlClient.ts 仍可对上述 GET 附带更多 query、对 POST 仍发送 JSON；FastAPI 对未声明的 query 通常忽略，不声明的 body 仍会被接收但不解析。
• OpenAPI：/sql/execute 与 POST /operation-logs 的文档中可能不再展示请求体 schema（与当前「不读 body」实现一致）。
• 破坏性变更：否（若客户端依赖 OpenAPI 生成且严格要求 taskId 出现在 schema，仅文档层面变化；运行时多传 taskId 仍被 Pydantic 忽略）。

4. 风险与回滚

• 风险级别：低。
• 回滚：回退本改动对应提交即可。

回滚方式是否简单：是。

5. 验证与测试

• 已执行：python -m py_compile api_server.py。