docs: 更新项目 README 和用户手册。

Author: OSpoon

README.md

@@ -32,43 +32,38 @@
 
 ### 🤖 AI 智能引擎 (Agentic Engine)
 
-- **Multi-Agent Workflow (LangGraph)**:
-  - **Supervisor**: 智能调度中心，根据问题深度自动编排工作流。
-  - **Discovery Agent**: 自动探索 Schema、Index Mapping 及多表关联关系。
-  - **Generator Agent**: 支持 Text-to-SQL 与 Text-to-Lucene，具备错误自修复能力。
-  - **Security Agent**: 实时审计生成的脚本，拦截危险操作并对 PII 数据进行脱敏。
-- **Dual-Mode Chat**:
-  - **SQL Agent**: 深度结合数据库 Schema，支持 Text-to-SQL、歧义主动询问 (Disambiguation) 与思维链展示。
-  - **Lucene Agent**: 专为 Elasticsearch 设计，支持 Index 发现、Mapping 解析与查询语句生成。
-- **Mind Chain**: 透明展示 AI 的推理过程 (Reasoning)、工具调用 (ListTables, ValidateSql) 与自我纠错逻辑。
+- **4-Agent Pipeline (LangGraph)**:
+  - **Supervisor**: 智能调度中心，作为入口节点分析用户意图，并将任务精准路由给正确的执行智能体。
+  - **Discovery Agent**: 自动探索 Schema 及多表关联关系，获取生成查询所需的上下文元数据。
+  - **Generator Agent**: 根据前置元数据生成准确的 Text-to-SQL 查询。该节点具备**错误自修复**能力。
+  - **Security Agent**: 独立的安全审计节点。一旦识别到 `DROP`, `TRUNCATE` 等高风险动作立刻阻断，并对 PII（敏感个人信息）执行自动脱敏。
+- **Agentic Chat**:
+  - **SQL Agent**: 深度结合关系型数据库 Schema，支持 Text-to-SQL、歧义主动询问 (Disambiguation) 与思维链展示。
+- **Voice Input**: 基于微信 JSSDK 与后端 API 的双模语音识别 (Transcription)，支持直接长按录音发送自然语言指令（针对移动端与桌面端分别适配优化）。
+- **Mind Chain & Graph Visualizer**: 透明展示 AI 的推理过程 (Reasoning)、工具调用 (如 `ListTables`, `ValidateSql`) 与自我纠错逻辑。左侧悬浮窗支持实时可视化节点流转路径。
 - **Knowledge RAG**: 将用户认可的优质 SQL 沉淀为知识库，增强 AI 在特定业务场景下的准确率。
-- **Hybrid AI Engine**: 支持同时接入 OpenAI 兼容模型 (如 GPT-4, DeepSeek) 与 智谱 AI (GLM-4) 等国产模型，灵活配置 Embedding 模型以优化 RAG 检索效果。
+- **Hybrid AI Engine**: 支持多模型并行接入 (如 OpenAI 兼容模型，DeepSeek，智谱 GLM-4)。支持将**聊天模型 (Chat Model)** 与 **向量模型 (Embedding Model)** 分离配置，以实现最佳性价比与检索效果。
 
 ### 🔌 多源数据接入
 
-- **Supported Sources**: PostgreSQL, MySQL, Elasticsearch, HTTP API (cURL 适配)。
-- **Auto-Discovery**: 自动扫描数据库元数据，利用 AI 识别手机号、邮箱等 PII 敏感字段并配置脱敏规则。
-- **Schema Sync**: 定时或触发式同步最新的表结构至向量数据库。
+- **Supported Sources**: PostgreSQL, MySQL, HTTP API (cURL 适配)。
+- **Auto-Discovery & Schema Sync**: 自动扫描数据库元数据并同步至向量数据库。利用 AI 自动识别（如手机号、邮箱）并配置 PII 数据脱敏规则。
 
 ### 🛡 安全与治理
 
-- **End-to-End Encryption**: 基于 `CryptoService` 实现敏感 API 负载的全链路加密，确保 API 密钥与敏感数据不可通过网络嗅探获取。
-- **Precision RBAC**: 基于角色的权限控制，严格实施最小权限呈现原则。Dashboard 支持系统级全量视图与个人专属版面的动态区隔。
+- **End-to-End Encryption**: 基于 `CryptoService` 实现敏感 API 负载的全链路加密，确保 API 密钥与敏感数据不在网络嗅探中泄露。
+- **Precision RBAC**: 基于角色的权限控制，严格实施最小权限呈现原则。Dashboard 支持系统级全量视图与个人专属版面的动态隔离。
 - **Enterprise-Grade Protection**:
-  - **OOM Defense**: 查询引擎自带行数熔断 (LIMIT 1000兜底)，阻止巨量数据拉垮服务器内存。
-  - **RCE Prevention**: 核心沙箱阻隔 Shell 元字符注入，彻底杜绝命令执行逃逸。
-  - **IDOR Proof**: 数据源探测和任务协同均具备行列级越权防御，普通员工无法窥探越权数据。
-- **安全过滤拦截**: 拦截 `DROP`, `TRUNCATE` 等高危动作，并对生成的查询进行强制验证。
-- **2FA**: 集成 Google Authenticator 双重认证。
+  - **OOM Defense**: 强制行数熔断 (兜底 LIMIT 1000)，阻止巨量数据压垮服务器内存。
+  - **RCE Prevention**: 核心沙箱阻隔 Shell 元字符注入，杜绝命令执行逃逸。
 
-### ⚙️ 自动化与触达
+### ⚙️ 自动化与持续集成
 
-- **Parameterized Scheduler**: 支持 Crontab 定时执行 SQL 报表任务，支持配置**动态占位符参数**，实现千人千面的自动化报表。
-- **AI Feedback Loop**: 用户可以直接对 AI 生成的 SQL/Lucene 进行评价与校正，系统支持从反馈中**自动学习**，持续提升准确率。
+- **Parameterized Scheduler**: 具备极高韧性的数据库驱动调度器。支持配置**动态占位符参数**，实现千人千面的自动化报表触达。
 - **Multi-Channel Push**:
   - **Email**: 自动发送带有数据的 CSV 附件。
   - **IM Webhook**: 支持企业微信、钉钉、飞书群机器人实时推送数据摘要。
-- **Mini Program**: 配套微信小程序，随时随地查看报表与历史记录。
+- **CI/CD & Docker Native**: 原生拥抱 Docker 部署，在 GitHub Actions 流水线中深度集成了针对后端数据库测试的专用 `docker-compose.test.yml` 验证机制，确保发布稳定性。
 
 ---
 
@@ -78,13 +73,14 @@
 
 | Component               | Status         | Description                                                                          |
 | :---------------------- | :------------- | :----------------------------------------------------------------------------------- |
-| **Multi-Agent Graph**   | ✅ Implemented | LangGraph-based workflow with Supervisor and specialized agents.                     |
+| **Multi-Agent Graph**   | ✅ Implemented | LangGraph-based 4-Agent workflow (Supervisor, Discovery, Generator, Security).       |
+| **Voice Input**         | ✅ Implemented | Cross-platform audio transcription via WeChat JSSDK & HTML5 MediaRecorder.           |
+| **Mini Program**        | ✅ Implemented | WeChat client for mobile Task Dashboard, Execution, and WeChat Login.                |
 | **Payload Encryption**  | ✅ Implemented | AES-256 encryption for sensitive data exchange using shared key.                     |
 | **AI SQL Generation**   | ✅ Implemented | Robust backend agent using LangChain, schema retrieval, and self-correction.         |
-| **Reasoning Display**   | ✅ Implemented | Users can see "thoughts" and "tool calls" (e.g., schema lookup, validation).         |
-| **Data Report Display** | ✅ Implemented | Results are rendered as an interactive table directly inside the chat.               |
-| **Code Editor**         | ✅ Implemented | Integrated **CodeMirror 6** with SQL/Lucene syntax highlighting and auto-completion. |
-| **Mobile**              | Uni-app + Vite | 跨平台小程序开发                                                                     |
+| **Reasoning Display**   | ✅ Implemented | Users can see "thoughts", "tool calls" (e.g., schema lookup), and node execution.    |
+| **Code Editor**         | ✅ Implemented | Integrated **CodeMirror 6** with SQL syntax highlighting and auto-completion.        |
+| **Hybrid AI Engine**    | ✅ Implemented | Split Chat/Embedding models via custom config (OpenAI/GLM/DeepSeek).                 |
 
 ---
 

docs/user_manual.md

@@ -33,49 +33,39 @@
 1.  **通用聊天 (General Chat)**
     - **如何触发**: 在左上角数据源选择框中选择 `Select Data Source` (空) 或 `No Context`。
     - **用途**: 询问通用问题，如“Excel 怎么算标准差？”、“解释一下什么是留存率”。
-    - **特点**: AI 不会尝试连接数据库，响应速度快。
+    - **特点**: AI 不会尝试连接数据库，响应速度极快。
 
-2.  **SQL 数据查询 (Agentic SQL)**
+2.  **SQL 数据查询 (Agentic Query)**
     - **如何触发**: 在左上角选择一个具体的数据源 (如 `Production DB`)。
     - **用途**: 获取具体业务数据。
     - **操作步骤**:
       1.  在对话框输入需求，例如：“查询上个月销售额最高的前 10 个商品”。
       2.  **换行技巧**: 输入框支持多行，按 `Shift + Enter` 换行，按 `Enter` 发送。
-      3.  **歧义处理**: 如果 AI 不确定您的意思（比如“销售额”是指下定金额还是实付金额），它会弹出选项供您选择。
-      4.  **结果验证 (Code Editor)**:
-          - AI 会生成 SQL 并自动填充到 **CodeMirror 6 Editor**。
-          - **Syntax Highlighting**: 支持 SQL 与 Lucene 语法高亮。
-          - **Auto-Completion**: 输入表名或字段名时尝试触发自动补全。
-          - **Run**: 点击三角图标或 `Cmd/Ctrl + Enter` 执行查询。
-          - **Download CSV**: 查询结果表格右上角提供下载按钮，支持一键导出 CSV。
+      3.  **歧义处理**: 如果 AI 不确定您的意思（比如“销售额”是指下定金额还是实付金额），它会主动询问并提供选项供您选择。
+      4.  **语音输入 (Voice Input)**: 在移动端或桌面端，您可以点击输入框右侧的麦克风图标，直接使用自然语言语音说出查询需求，系统会自动将其转换为文字。
+      5.  **结果验证 (Code Editor)**:
+          - AI 会生成查询代码并自动填充到 **CodeMirror 6 Editor**。
+          - **Syntax Highlighting**: 支持 SQL 语法高亮。
+          - **Auto-Completion**: 在输入表名或字段名时尝试触发数据库自动补全。
+          - **Run**: 点击执行按钮运行代码。
+          - **Download CSV**: 查询结果表格支持一键导出 CSV。
 
 ### 2.2 智能调度与多智能体协作
 
-NexQuery 采用先进的 **Multi-Agent** 架构，系统会自动启动多个专家智能体协同工作：
+NexQuery 采用先进的 **4-Agent Pipeline** 架构，系统会自动启动不同的专家智能体协同工作：
 
-- **Supervisor (主管)**: 分析您的意图，编排任务。
-- **Discovery (探索者)**: 自动查找表结构、索引和字段含义。
-- **Generator (生成者)**: 编写 SQL 或 Lucene 语句并进行校对。
-- **Security (卫兵)**: 检查语句安全性并对敏感 PII 数据执行脱敏。
+- **Supervisor (主管)**: 作为大脑分析您的意图，规划任务路径并将其分配给合适的智能体。
+- **Discovery (探索者)**: 自动查找表结构和字段含义。具备智能缓存机制以加快响应速度。
+- **Generator (编写者)**: 负责推理和编写最终的 SQL 语句，并具备在出错时自我修复重试的能力。
+- **Security (安全卫兵)**: 独立的安全审核环节，在试运行后对敏感 PII 数据执行自动脱敏，并拦截高危动作。
 
-**Mind Chain (思维链)**: 在对话过程中，点击“查看推理过程”可以实时观察各智能体的思考逻辑、工具调用及自我修补过程。
+**Mind Chain (思维链)**:
+在对话过程中，点击“查看推理过程”可以实时观察该 4-Agent 架构的思考逻辑、工具调用图及自我修补过程。
 
 **Graph Visualizer (流程可视化)**:
-点击聊天窗口右上角的 **Mermaid** 图标，悬浮窗将实时展示 Multi-Agent 的工作流状态：
+点击聊天窗口右上角的 **Mermaid** 图标，悬浮窗将实时展示智能体工作流状态，蓝色节点代表当前激活的执行路径。
 
-- **Running (Active)**: 当前正在执行的节点会高亮闪烁。
-- **Path**: 连线展示了 Agent 之间的跳转逻辑 (e.g., Supervisor -> Discovery -> Generator)。
-- **Debug**: 配合思维链，可用于排查 AI 为何陷入循环或选择了错误的工具。
-
-### 2.3 Elasticsearch 查询 (Lucene)
-
-对于日志分析或全文检索场景，NexQuery 支持连接 **Elasticsearch**。
-
-- **智能识别**: 选择 ES 数据源后，AI 自动切换为 **Lucene Agent**。
-- **查询能力**: 支持通过自然语言生成 Lucene 语法。
-- **探索工具**: AI 会自动发现 Index Mapping 和字段统计信息。
-
-### 2.4 智能优化
+### 2.3 智能优化
 
 如果您懂 SQL，可以在编辑器写好 SQL 后点击 **Optimize SQL**。AI 会分析您的查询，并给出通过加索引或重写语句来提升性能的建议。
 
@@ -109,55 +99,56 @@ NexQuery 采用先进的 **Multi-Agent** 架构，系统会自动启动多个专
 
 ## 4. 移动端 (小程序)
 
-NexQuery AI 提供配套微信小程序，方便随时随地看数。
+本系统原生提供微信小程序客户端 (UniApp)，方便您在移动端随时随地进行数据协作。
+
+### 4.1 微信登录与绑定
+首次在小程序侧登录时，系统会拉取您的微信一键登录授权，并自动与后端的 Web 账号进行安全绑定。
 
-- **绑定**: 首次使用小程序需输入 Web 端账号密码进行绑定。
-- **功能**:
-  - 查看所有已保存的查询任务。
-  - 执行任务并预览结果 (表格/JSON)。
-  - 查看历史执行记录。
+### 4.2 移动端核心场景
+- **任务大盘**: 浏览企业内公开共享的 (Public) 以及您个人的 (Private) 定时查数任务。
+- **一键执行任务**: 手指轻点，输入动态参数，即可在微信界面中直接运行复杂的数据模型并查看结果。
 
 ---
 
 ## 5. 管理员指南 (Administration)
 
 如果您是管理员，以下功能将帮助您更好地理系统。
 
-### 5.1 数据源管理 (Data Sources)
+### 4.1 数据源管理 (Data Sources)
 
 - **PII 自动发现**: 添加数据源后，系统会自动扫描敏感字段。请在 Settings 中复核这些标记，确保手机号、身份证等数据被正确脱敏 (Masking)。
 - **Schema Sync**: 建议定期点击 Sync 按钮，确保 AI 掌握最新的表结构。
 
-### 5.2 数据大盘与视图隔离 (Dashboard Isolation)
+### 4.2 数据大盘与视图隔离 (Dashboard Isolation)
+
+系统的仪表盘具备基于角色的智能防窥探机制：
 
-系统的仪表盘具备智能防窥发机制：
+- **上帝视角 (Admin View)**: 作为超级管理员，您可以俯瞰整个系统的吞吐量、资源载荷，以及 "Top Users" 最活跃用户排行榜，纵览全区数据请求概况。
+- **隐私视图 (Operator View)**: 对于普通的分析用户，看板会自动将数据面降级为“个人工作台”。只允许聚合和展示其**个人产生**的查询量及执行图表，自动隐藏全网敏感数据与组织内部的资源消耗榜单。
+- 支持在右上角无缝切换 **7d / 30d / 90d / 全部** 的监控监控时间跨度。
 
-- **上帝视角 (Admin View)**: 作为管理员，您可以俯瞰整个系统的吞吐量、资源载荷，以及 "Top Users" 最活跃用户排行榜。
-- **隐私视图 (Operator View)**: 对于非管理员权限的用户，看板会自动将数据面降级为“个人工作台”。只允许聚合和展示其个人产生的查询量及执行图表，自动隐藏全网敏感数据与榜单。
-- 您随时可以在右上角无缝切换 **7d / 30d / 90d / 全部** 的监控跨度。
+### 4.3 AI 治理与闭环学习 (Feedback)
 
-### 5.3 AI 治理与闭环学习 (Feedback)
+在 **AI Feedback** 菜单中，您可以查看用户在聊天窗口对智能体生成的 SQL 和查询结果进行的反馈记录：
 
-在 **AI Feedback** 菜单中，您可以查看用户在聊天窗口进行的反馈记录：
+- **满意度收集**: 用户通过点赞/点踩快速表态。
+- **用户校正 (Correction)**: 如果 AI 生成的 SQL 有误或非最优解，懂代码的用户可以直接提供正确的代码片段。
+- **自动学习 (Adopt & Learn)**: 管理员在后台审核这些反馈后，点击 **Promote**。系统会将该优质案例**无缝同步到双模知识库**。
+- **知识库加持**: 知识库内部现已独立支持 SQL 引擎。AI 会在下次面临类似意图检索时自动根据当前数据源装载对应的记忆，实现“越用越聪明”。
 
-- **点赞/点踩**: 快速收集用户对生成结果的满意度。
-- **用户校正 (Correction)**: 如果 AI 生成的 SQL/Lucene 有误，用户可以提供正确的代码。
-- **自动学习 (Adopt & Learn)**: 管理员审核反馈后，点击 **Promote**。系统会将优质案例**自动同步到知识库**，提升 AI 在下次遇到类似问题时的生成准确率。
-- **双模知识库**: 知识库现已支持 **SQL** 和 **Lucene** 两种类型。AI 会在检索时自动根据当前数据源加载对应的知识。
+### 4.4 Hybrid AI 灵活配置 (Hybrid AI Engine)
 
-### 5.4 Hybrid AI 配置 (Hybrid AI Engine)
+管理员可以在 **Settings -> AI** 面板中非常灵活地配置不同的底层 AI 模型与服务商。NexQuery 首创了**推理与检索解耦**的模型配置方案：
 
-管理员可以在 **Settings -> AI** 中灵活配置不同的模型提供商：
+- **Chat Model (推流与执行引擎)**: 负责负责上下文理解、意图分析、流式工作流推理与代码生成。推荐使用能力极强的模型 (如 `GPT-4o`, `DeepSeek-Reasoner`, 智谱 `GLM-4`)。
+- **Embedding Model (向量检索引擎)**: 专门负责长文本的知识库与 Schema 字典的向量化检索。
 
-- **Chat Model**: 负责逻辑推理与生成 (e.g., GPT-4o, GLM-4)。
-- **Embedding Model**: 负责知识库与 Schema 的向量化检索 (e.g., text-embedding-3-small)。
-- **配置项**:
-  - `AI Base URL` & `AI API Key`: 用于 **Chat Model**。
-    - **OpenAI**: `https://api.openai.com/v1`
-    - **DeepSeek**: `https://api.deepseek.com`
-    - **Zhipu AI**: `https://open.bigmodel.cn/api/paas/v4/`
+- **配置项说明**:
+  - `AI Base URL` & `AI API Key`: 用于配置 **Chat Model**。
+    - **OpenAI 兼容平台**: 填写对应平台的 URL (如 `https://api.deepseek.com` 或 `https://api.openai.com/v1`)
+    - **智谱原生 SDK**: 平台原生集成支持调用 `https://open.bigmodel.cn/api/paas/v4/`
   - `AI Embedding Base URL` & `AI Embedding API Key`: 独立配置 **Embedding 服务**。
-    - _Scenario_: 您可以使用便宜的 `text-embedding-3-small` (OpenAI) 处理向量检索，同时使用 `DeepSeek-V3` 处理复杂的逻辑推理，实现**最佳性价比**。
+    - _应用场景_: 由于向量检索调用非常高频且消耗大量 Token，您可以将这里配置为市面上性价比极高、专门用于搜索的模型 (例如 OpenAI 的 `text-embedding-3-small` 甚至是本地的私有化小模型 API)，而将负责极其复杂逻辑推理的 Chat Model 设定为 `DeepSeek-V3`。**以此实现最完美的性能与成本双赢方案**。
 
 ---