NL2SQL Assistant
中文 | English
用自然语言生成 SQL：双模式 Schema（手动粘贴 / 自动扫库）+ 本地智能选表，面向"不会写 SQL、记不住表结构、接手新项目不知道该选哪些表"的开发者。
当前状态：v0.0.5 已发布到 VS Code Marketplace（手动模式 + MySQL/PostgreSQL 自动扫库）
已实现：侧边栏面板、命令面板入口、手动 Schema 模式（粘贴或从编辑器导入）、MySQL 与 PostgreSQL 自动扫描表结构（MySQL 用 SHOW CREATE TABLE 保精度；PostgreSQL 支持多 schema 范围选择，表列表按 schema 分组）、按需查看任意表的建表语句、表结构缓存与强制刷新、智能选表（含两跳外键链路）、上下文裁剪、流式生成与停止、结果面板（SQL + 中文说明 + 引用表）、高危提示与严格模式、插入编辑器（保持缩进）、历史记录、代理与证书支持、数据出境告知、平台支持判定（Web 版明确不支持）、模型与数据库连接均在面板内配置、凭证存 SecretStorage。由 145 个 Node 单测 + 24 个扩展宿主集成测试覆盖（含真实 MySQL 8.0.27 的 300 表扫描与真实 PostgreSQL 15 的多 schema 用例）。
待办：Remote-SSH 手工验证（AC25）、Open VSX 发布凭证。需求与验收标准见 specs/0001-initial/spec.md，实施方案见 plan.md，进度见 tasks.md。原始 PRD 保留在 docs/prd.md。
功能（V1.0 目标）
| 能力 |
说明 |
| 双模式 Schema |
手动粘贴建表语句（离线可用）／连接数据库自动扫描（MySQL、PostgreSQL，支持多 schema） |
| 本地智能选表 |
零 token、无网络的关键词评分 + 外键一跳扩展，展示命中理由；注释覆盖率低时明确提示精度下降 |
| 上下文预算 |
按模型预算分层裁剪 Schema 并展示裁剪明细，超限降级而不是把请求发爆 |
| 多模型接入 |
OpenAI 兼容端点优先（覆盖 Kimi、通义千问兼容模式、本地服务）与 Ollama；支持流式与停止生成 |
| 生成与操作 |
中文需求 → SQL + 中文逻辑说明 → 复制 / 插入编辑器，支持多轮迭代与历史记录 |
| 安全基线 |
凭证仅存 SecretStorage、日志脱敏、工作区信任模型、首次云端调用前的内容告知 |
明确不做（V1.0）：不执行 SQL、不返回查询结果；不支持 SQL Server / Oracle；不支持 VS Code Web（vscode.dev）；不做 SQL 语法校验与索引优化建议；界面仅中文（英文见本 README）。
安装
可通过以下任一方式安装：
- VS Code Marketplace 搜索
NL2SQL Assistant，或打开 https://marketplace.visualstudio.com/items?itemName=sql668.nl2sql-assistant。
- 命令行：
code --install-extension sql668.nl2sql-assistant。
- 离线安装：下载
.vsix 后在扩展面板选择"从 VSIX 安装"，或执行 code --install-extension nl2sql-assistant-<version>.vsix。
Open VSX（VSCodium、Eclipse Theia 等）尚未发布：暂无该市场凭证，补齐后可复用同一份 vsix。
本地自测可直接用打包产物：npm run package:vsix 会生成 nl2sql-assistant-<version>.vsix（实测约 759 KB，不含测试产物）。
配置
配置项前缀统一为 nl2sql-assistant.：
| 配置项 |
说明 |
nl2sql-assistant.connections |
数据库连接列表（环境名、类型、host、port、库名、用户）；不含密码 |
nl2sql-assistant.activeConnection |
当前使用的连接（dev / test / prod） |
nl2sql-assistant.provider |
模型服务商与 baseURL、模型名；不含 API Key |
nl2sql-assistant.cacheTtlHours |
表结构缓存有效期（默认 24 小时） |
nl2sql-assistant.schemaTokenBudget |
生成请求的上下文预算上限与裁剪策略开关 |
nl2sql-assistant.strictMode |
严格模式：不生成高危 SQL，改为给出改写建议 |
模型配置有三种方式，任选其一：
- 直接在侧边栏面板里填（推荐）：展开"模型配置"，填 Base URL、模型名称与 API Key，点【保存配置】。保存后立即生效，不需要改设置文件或重载窗口；已保存过 Key 时按钮区会出现【清除 Key】。
- 命令面板：
NL2SQL Assistant: 配置模型端点 —— 选服务商预设（DeepSeek / OpenAI / Kimi / 通义千问兼容模式 / Ollama / 自定义）后自动带出默认值。
- 手改设置：编辑用户设置的
nl2sql-assistant.provider（对象：baseUrl / model / 可选 proxy）。
如果工作区设置里已经显式定义过 nl2sql-assistant.provider，面板保存会写入工作区作用域（避免被工作区覆盖后"看起来没生效"）；否则写入用户设置。
数据库连接同样在面板里配：展开"数据库连接"→ 填标识（英文小写，如 dev）、显示名称、类型（MySQL / PostgreSQL）、主机、端口、库名、账号、密码 → 点【保存连接】。保存后立即成为当前连接，可直接【测试数据库连接】或【扫描数据库】；可保存多套连接并用下拉框切换，切换会自动尝试用该连接的缓存恢复表结构（不连库）。PostgreSQL 还可以用【Schema 范围】按钮勾选要扫描的 schema。
连接的非敏感字段最终存在设置里（nl2sql-assistant.connections），密码与 API Key 一样只进 VS Code SecretStorage（操作系统钥匙串），不写入 settings.json，面板也从不回显明文。
命令
| 命令 |
说明 |
nl2sql-assistant.openPanel |
打开侧边栏面板（主入口） |
nl2sql-assistant.importSchemaFromEditor |
把当前编辑器选中的建表语句导入 Schema 区 |
nl2sql-assistant.scanDatabase |
扫描当前连接的库表元数据（可取消） |
nl2sql-assistant.recommendTables |
按需求做本地智能选表推荐 |
nl2sql-assistant.generateSql |
生成 SQL 与中文逻辑说明 |
nl2sql-assistant.insertSql |
把结果插入编辑器光标处 |
nl2sql-assistant.clearHistory |
清空对话与历史记录 |
隐私与安全
- 只读元数据：插件自身只读取表名、字段、注释等元数据，不查询业务数据。
- 执行边界：V1.0 不执行 SQL。把 SQL 插入编辑器属于文本插入，插件无法、也不承诺阻止你在别处执行。
- 凭证存储：数据库密码与 API Key 仅存于操作系统钥匙串（VS Code SecretStorage），配置文件与导出内容不含密钥；日志、错误提示与剪贴板内容统一脱敏。
- 数据出境：使用云端模型时，表名、字段、注释与你的自然语言需求会发送到你所配置的模型端点。首次使用前会明确告知并要求确认；改用本地 Ollama 则不出网。
- 工作区信任：在不受信任的工作区中，扫描数据库与生成 SQL 会被禁用。
- 高危 SQL：识别 DROP / TRUNCATE / 无 WHERE 的 UPDATE 或 DELETE，渲染期红色标记并要求二次确认；严格模式下改为给出改写建议。
开发
npm install
npm run compile # 编译
npm run lint # 静态检查
npm run test:unit # Node 单测：核心逻辑与 Provider（无需启动 VS Code）
npm run eval:recommend # 推荐评测集（基于公开示例库 sakila）的 precision@5 / recall@5
npm test # 扩展宿主集成测试（@vscode/test-cli，首次会下载 VS Code 运行时）
数据库扫描的集成测试需要一个本地 MySQL：./scripts/dev-mysql.sh start 会起一个独立实例在 127.0.0.1:3307（不碰系统默认的 3306）；未启动时相关用例自动跳过。
PostgreSQL 用例（多 schema）需要本地 PostgreSQL 15：./scripts/dev-postgres.sh start 会用 Docker 起在 127.0.0.1:5433；未启动时同样自动跳过。
发布前的手工验收步骤见 docs/manual-test.md（含 F5 调试宿主、测试数据准备与分模块检查清单）。
调试：用 VS Code 打开本目录，按 F5 启动扩展开发宿主。面板位于活动栏的 NL2SQL Assistant 图标下（侧边栏视图）。
发布
当前状态：0.0.5 已于 2026-09-25 发布到 VS Code Marketplace（0.0.3 为首次发布；0.0.4 排除误打包的 out/test/**；0.0.5 补上 128×128 市场图标）。同一份 vsix 可同时发布到两个市场：
npm run package:vsix # 生成 vsix（带 baseContentUrl，保证 README 相对链接可解析）
npx @vscode/vsce publish --packagePath nl2sql-assistant-<version>.vsix # VS Code Marketplace
npx ovsx publish nl2sql-assistant-<version>.vsix --pat <token> # Open VSX
发布凭证（PAT）不写入仓库与配置文件，本机由 vsce login <publisher> 存入系统钥匙串。
规格与流程
本插件遵循仓库的 SDD + harness 规范（仓库根 AGENTS.md、docs/sdd-harness.md）：
- 改动前先在
specs/NNNN-slug/ 建规格，实现后把证据写进 tasks.md。
- 新规格：
npm run new:spec -- "<标题>" --plugin nl2sql-assistant --slug <ascii-slug>。
- 完成前在仓库根目录运行
npm run harness（改了代码逻辑再跑 npm run harness:deep）。
- 文档语言：界面与本文档为中文，同时维护 README.en.md；标识符与命令 ID 使用英文。
