Enhance SQL generation and streaming capabilities in the API server. Introduce optional parameters for streaming throttle and SQL stream granularity in NLChatRequest. Implement new functions for iterating SQL generation content pieces and adjusting streaming behavior based on user-defined settings. Update prompts for few-shot SQL adaptation and improve logging for SQL generation processes. Refactor orchestrator methods to support streaming responses and integrate few-shot SQL conditions. Update impact analysis documentation to reflect these changes.

IMPACT_ANALYSIS.md

@@ -592,3 +592,83 @@
 ## 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`）。
+- **改动类型**：行为调整（默认分片粒度默认更贴近前端的 `char`；可配置回 `delta`）。
+
+## 2. 方法级改动
+
+| 位置 | 变更 |
+|------|------|
+| `NLChatRequest` | 新增可选 `sql_stream_granularity`（`sqlStreamGranularity`）；明确 `streaming_throttle` 为相邻 content 间隔毫秒。 |
+| `_iter_sql_gen_content_pieces` | 支持传入 `mode`；未设置时 `SSE_SQL_GEN_SPLIT` 默认 `char`。 |
+| `_chat_stream_events` | sql_gen 循环按粒度拆分后对每条 `data` 可选 `asyncio.sleep(throttle)`；寒暄分支 `_sse_stream_text_chunks` 支持相同节流。 |
+
+## 3. 调用方与影响范围
+
+- **调用方**：仅 SSE 流式客户端；非流式 `/g3sb/api/nl/chat` 不变。
+- **破坏性变更**：否。未传新字段时：粒度由 `SSE_SQL_GEN_SPLIT` 决定（默认 `char`，事件条数多于旧版 `delta`）；若需旧行为可设 `SSE_SQL_GEN_SPLIT=delta` 或请求体 `sqlStreamGranularity: "delta"`。
+
+## 4. 配置变更
+
+| 环境变量 | 含义 | 默认 |
+|----------|------|------|
+| `SSE_SQL_GEN_SPLIT` | `char`：逐 Unicode 标量多条 SSE；`delta`：与 LLM 增量一致 | `char`（未设置 env 时由代码默认） |
+
+## 5. 风险与回滚
+
+- **风险级别**：低。`char` 模式下 SSE 条数增加，带宽与前端拼接次数上升。
+- **回滚**：设 `SSE_SQL_GEN_SPLIT=delta` 或请求传 `sqlStreamGranularity: "delta"`。
+
+**回滚方式是否简单**：是。
+
+## 6. 验证与测试
+
+- 已执行：`python -m py_compile api_server.py`。