产品介绍：Query Toolkit

一、基本信息

● 软件名称：Query Toolkit
● 运行环境：Windows 10/11
● 安装包信息：大小约75M，双击直接运行（免安装）
● 下载地址：
● 功能简介：Query Toolkit 是一款 Windows 桌面端轻量数据查询工作台，目标是把“查询”做到极致。不仅逐一优化 Oracle SQL Developer 等 IDE 查询体验欠佳的地方，而且还根据实际工作场景，增加了自建表格的批量检索功能。

二、目标用户

1. 日常频繁使用Oracle SQL Developer、PL/SQL Developer 等IDE进行查询、导出等操作，查询常用的脚本多达几百个。
2. 日常频繁在多个Excel表格中检索信息。

三、解决的主要问题

1. 有几百个常用SQL查询脚本，不容易找，不方便维护。
2. 同样的脚本，想在不同的数据库查询，但是不得不在不同查询窗口中复制粘贴。
3. 一次执行多个SQL，查询结果不方便一键导出Excel。
4. 一次执行多个SQL，查询结果不方便一键转换成Delete+Insert脚本。
5. 编辑好的数据表格，不方便转换成Insert脚本。
6. 手头有十多个格式不同、至少几千行的表格，无法在所有表格中同时搜索。

四、一定不做的事情

1. 不执行任何写库操作（INSERT/UPDATE/DELETE/DDL）。
2. 不做服务端，不做多端同步，不做团队协作。
3. 不做纯离线承诺。因为连接远程 Oracle 仍需网络，只有脚本、自建表格、配置是本地存储。
4. 不替代专业数据集成工具（ETL）。只覆盖“查询转 DELETE+INSERT”和“CSV 转 INSERT”这两类高频场景。
5. 不支持 macOS 和 Linux。目标环境仅为 Windows 10/11。

五、功能模块简介

1 登录

首次使用时，默认免登录——设置页面的密码锁为未开启状态。
启用密码锁后，导航出现”锁定/退出”。未使用时长超过阈值后（默认 15 分钟，可设 1~480）需解锁。

2 ESQL（查询远程Oracle数据库）

2.1 多标签页独立会话

1. 每个标签页持有独立的连接选择、脚本、编辑器内容/光标/撤销历史、查询状态、结果与分页，标签之间互不串用。
2. 同一脚本可以在不同标签里用不同连接分别打开，并行执行互不覆盖。
3. 操作方式：Ctrl+T 新建、单击切换、双击重命名、单击[×]按钮关闭。

2.2 SQL 编辑器

1. 语法高亮：基于 CodeMirror 6，支持 Oracle / SQLite 两种方言，多套配色可在界面设置中即时切换。
2. 基础编辑能力：行号、当前活动行高亮、括号匹配、代码折叠、多光标、撤销/重做、查找/替换、自动换行。
3. 自动补全：SQL 关键字 + 表名/列名。列补全按需加载——识别到当前 SQL 引用了哪张表，才单独查询那张表的列并缓存复用，SQLite 与 Oracle 均支持；补全加载失败不影响手工执行。
4. 格式化：按当前方言格式化选区或全文，一次格式化对应一次撤销，改坏了可以一步退回。
5. 光标位置：底部状态栏实时显示光标所在行、列及选中字符数。

2.3 SQL 执行

1. 智能分句：一次可执行多条 SQL，按 ; 与 {|} 自动分句；字符串、注释、Oracle q 引号里的分号不会被误拆；最后一条不写分号也会执行。
2. 逐条状态：每条语句独立记录排队/执行中/成功/失败/未执行、列、行数、耗时与错误；中间某条失败会记录原因并继续下一条。
3. 实时进度：执行中信息条滚动显示”开始查询时间 · 已耗时秒数 · 已完成 X/Y”。
4. 后台执行：SQL 在 worker 线程运行，重查询期间界面不卡死、可以继续操作。
5. 真正停止：点”停止”会中断 Oracle 当前执行（breakExecution）或终止 SQLite 任务线程，不是只隐藏进度。
6. 行数上限与警示：可选 10 万（默认）/50 万/100 万/500 万；返回行数达到上限时，结果区顶部以琥珀色横幅警示”实际数据量可能超过上限”，提示提高上限或缩小条件后重查。

2.4 只读安全拦截

1. 只允许查询：仅 SELECT、WITH…SELECT 类语句可执行；这是”绝对安全，无法执行任何增删改”承诺的技术兑现。
2. 整批拦截：批处理中只要含 INSERT/UPDATE/DELETE/DDL、事务命令、过程调用、PL/SQL 块、FOR UPDATE、NEXTVAL 之一，整批一条都不执行并给出明确原因——不剔除部分执行，避免误以为全部成功。
3. 编辑不受限：写库语句仍可自由编辑、格式化、保存，只在执行入口拦截。
4. 内部查询不误伤：读取表结构等内部元数据行为（如 PRAGMA table_info）不走面向用户的只读校验，SQLite 连接下查看表结构不会被误拒。

2.5 脚本管理

1. 全套操作：新建、保存、另存为、复制、重命名/改类型/改备注、删除、放弃修改；重命名和改备注不会清空正文、频率与启用状态。
2. 按脚本独立草稿：每个脚本按 ID 保存独立草稿与已保存基线，另有一个未命名草稿；切页、切脚本、退出重启后未保存内容都能恢复。
3. 未保存标记：草稿与基线不一致时，列表项与标题旁显示标记，一眼看出哪些还没落库。
4. 快速搜索：空格分隔多关键词按 AND 组合，可按类型筛选、可选搜索 SQL 正文；搜索在后端进行并有 300ms 防抖，快速连续输入时旧响应不会覆盖新结果。
5. 频率排序：每次成功执行递增该脚本的使用频率，列表按频率优先排序，越常用的脚本越靠前。
6. JSON 导入导出：脚本可整体备份为 JSON，也可批量导入迁移到新电脑。

2.6 结果表格与导出

1. 固定行号与表头：任意方向滚动时行号列和表头始终可见，翻页后行号连续。
2. 列宽自适应：按内容自动估算列宽（80~360px）；可拖动列边界，双击恢复该列最佳宽度，”全部最佳列宽”一键重算；手工调过的宽度翻页不被覆盖。
3. 分页浏览：每页 100/500/1000 可选，提供首页/上一页/下一页/末页。
4. 多结果切换：一批多条 SQL 时结果按 SQL1、SQL2… 标签切换，标签带状态标记，出错可定位到源 SQL。
5. 取值显示：NULL 以斜体显示、空串显示为空，二者可区分；超长值双击单元格弹出完整内容并可复制。
6. 复制：框选区域 Ctrl+C 或右键复制；”复制全部(TSV)”把整个结果集（不只当前页）复制成制表符分隔文本，直接粘贴进 Excel。
7. 独立结果窗口：把当前结果另开窗口按快照展示，主窗口继续查询不影响它。
8. 导出：当前/全部结果可导 Excel/CSV，全部结果支持合并单工作表或分工作表；导出自动附一张”查询脚本”信息页，记录连接名、脚本名、实际执行的 SQL、行数上限、执行时间与时长、截断/错误状态（不含密码）。

2.7 生成工具（只生成、不执行）

1. 批量 S2DI：把查询结果转成目标表的 DELETE+INSERT 脚本；简单单表 SELECT 自动提取目标表，JOIN、子查询等复杂 SQL 需明确目标表与键列。
2. 字段名对齐：INSERT 字段名按目标表真实字段生成——列名本身就是字段的直接用；仅涉及一个字段的表达式（如 TRIM(X)）自动映射到该字段；仍对不上的该条不生成并提示改写为同名字别名，绝不默默剔除列（否则 DELETE+INSERT 会把原值写成空）。
3. 截断保护：结果达到行数上限、可能不完整时，不允许直接生成，防止按截断数据交付。
4. 全表 DELETE 单独确认：生成的脚本中含无 WHERE 的 DELETE 时需单独确认。
5. 表 2 Ins：把 CSV 文件转成 INSERT 语句；支持引号内逗号、双引号转义、跨行字段、UTF-8 BOM / GBK；表头允许是目标字段的子集，空单元格默认生成 NULL，日期/数字按目标类型生成字面量。
6. 预览与保存：生成结果先预览、可保存为 .sql 文件，由人工审阅后拿到目标库执行——工具本身永不执行写库脚本。

3 EDict（查询自建数据表格）

3.1 导入与管理

1. 导入 CSV 建表：表名可自定义，留空时用文件名。
2. 导入、删除后表列表、当前选择与结果自动同步刷新，多窗口之间也同步。
3. 支持从 Python 版数据文件 edict.db 迁移：依次做 WAL 检查、完整性校验、带时间戳备份，按表勾选合并或覆盖，成功后原子切换，任一步失败不损坏现有数据。
4. 删除表需确认，操作不可撤销。

3.2 搜索

1. 多关键词空格分隔按 AND 组合；范围可选”全部表”（默认）或”当前表”。
2. 结果按表分组显示，每组给出命中总行数，并可各自翻页，沿用本次搜索的关键词与范围。
3. 明确区分五种状态：浏览、搜索中、有结果、无匹配、失败。
4. 可在设置开启即时搜索（输入停顿 100ms 自动执行）与二次搜索（在已有结果中继续筛选）。

3.3 多标签

1. 与 ESQL 同款标签模型：不同标签分别浏览/搜索不同的表，互不串用。
2. 切换标签不会自动重新搜索，已有结果保留。

4 设置

4.1 数据库连接

1. 新建/编辑/删除/启停连接；Oracle 连接串支持 user/pass@host:port/service_name 常见三种格式与 URL 编码字段，SQLite 填数据库文件绝对路径。
2. 连接列表支持关键词搜索。
3. 连接测试状态机：”测试中/成功/失败/超时”四态并显示耗时，防止重复点击；测试使用点击时的表单快照，修改参数或切换连接后旧结果作废。
4. Oracle 真实探测：执行真实连接与探测查询，错误分类提示（格式、网络/超时、服务名、认证、驱动），30 秒截止，任何提示均不显示密码。
5. SQLite 严格验证：必须真实打开数据库并读取内容，普通文本文件、空文件、损坏库、目录都不算连接成功。

4.2 SQL 脚本集中管理

1. 按类型/关键词/启用状态筛选，逐条新建、编辑（内置 CodeMirror 编辑器）、删除、启停。
2. JSON 批量导入导出；”删除全部”需手动输入 DELETE ALL 确认，防误删。

4.3 导出设置

1. 默认导出目录可选择、更改、一键打开；结果导出、生成脚本、日志导出都落到这里。
2. 未设置时使用系统文档目录。

4.4 界面设置

1. 外观：5 套配色 × 深浅两种模式独立组合（默认靛蓝深色）、三档控件间距、SQL 高亮配色切换，全部即时生效并记住，不改变布局。
2. 打开方式：模块可在页内标签或独立窗口打开（对新打开的模块生效）。
3. 安全卡片：密码锁开关、闲置时长、设置密码、立即锁定。
4. EDICT 卡片：即时搜索、二次搜索开关。

4.5 日志管理

1. 运行日志收集默认关闭，仅内存保留、重启不恢复。
2. 支持按级别/类别/条数筛选、展开查看详情、清空、导出 JSON/TXT。
3. 时间统一按本地时间显示（磁盘存储仍为 UTC），避免和应用时间对不上。

4.6 Debug 模式

1. 一键开关，开启后自动开始收集运行日志。
2. 悬停识别：鼠标停在界面任意位置，浮层显示该位置的中文名称 + 英文代码；控件显示自身名（如「执行整个脚本 / runScript(all)」），空白或容器回退到所属区域名（如「顶部导航栏」「结果区」）。向开发者反馈问题时，引用浮层中文名就能说清”在哪里、看到了什么”。
3. 操作日志：界面事件与各操作的 IPC 调用（通道、入参预览、耗时、失败原因）记入日志，便于排查。
4. 敏感脱敏：密码等字段自动掩码；Debug 面板自身的轮询通道不记录，避免刷屏。

4.7 数据迁移

1. 选择旧 Python 版 TBA 目录后，扫描”数据库连接 / SQL 脚本 / EDICT 数据”三类源数据量。
2. 逐项独立导入，逐条/逐表实时进度条，导入完成后展示总量与各分类数量。

六、使用的外部库

Query Toolkit 不重复造轮子：编辑器、数据库驱动、Excel/CSV 读写全部直接采用成熟开源库，把开发精力集中在产品逻辑本身。

1 Electron（桌面应用框架）

1. 好处：把 Chromium + Node.js 打包成 Windows 桌面程序，一套 Web 技术栈做界面，同时能直接用 Node 访问数据库和文件系统。
2. 对应功能：约 75M 的便携版 exe 双击即用免安装；窗口位置大小记忆；独立结果窗口；模块页内标签/独立窗口两种打开方式。
3. 用法：双进程架构——主进程负责数据库连接、查询 worker 线程、文件读写与日志收集，渲染进程跑 Vue 3 界面，两者通过 IPC 通道通信。Debug 模式能把每个操作的 IPC 调用（通道、入参、耗时）记入日志，正是建立在这个结构上。

2 CodeMirror 6（SQL 编辑器内核）

1. 好处：当前最主流的开源代码编辑器，按功能拆成 state/view/lang-sql/autocomplete/search/commands/lint 等多个小包，按需组装、扩展性强，官方内置 SQL 语言支持。
2. 对应功能：2.2 的全部编辑体验——语法高亮、行号、活动行、括号匹配、代码折叠、多光标、查找/替换、自动补全、撤销/重做。
3. 用法：用 @codemirror/lang-sql 分别配置 Oracle/SQLite 方言；把数据库的表名/列名做成自定义补全数据源，配合按需加载的列缓存（引用到哪张表才查哪张表，切连接即清空）；利用 EditorState 天然按文档独立隔离的特性，实现 2.1 每标签独立内容与撤销历史；高亮主题与界面设置的多套配色联动。设置页的脚本编辑弹窗内置的同款编辑器也是它。

3 sql-formatter（SQL 格式化）

1. 好处：开源 SQL 美化器，原生支持 Oracle 与 SQLite 方言，省去自写格式化器的巨大工作量。
2. 对应功能：Shift+Alt+F 格式化选区或全文。
3. 用法：按当前连接的方言调用，格式化结果作为一个事务写回 CodeMirror 文档，因此”一次格式化对应一次撤销”。

4 oracledb（Oracle 官方 Node.js 驱动）

1. 好处：Thin 模式直连数据库，用户无需安装 Oracle Instant Client，装完应用就能连库。
2. 对应功能：连接管理与连接测试（错误分类、30 秒截止）；SQL 执行；”停止”按钮真正中断查询；字段补全与 S2DI 字段对齐所需的表结构元数据查询。
3. 用法：查询在 worker 线程中执行避免阻塞界面；点停止时调用 breakExecution 中断当前执行；表字段清单统一查 all_tab_columns（带 owner 过滤），保证通过同义词访问的他人表也能取到字段。

5 sql.js（SQLite 引擎，WebAssembly 版）

1. 好处：SQLite 官方源码编译成 WASM，纯 JS 运行、免原生模块编译，在 Electron 主进程即拿即用。
2. 对应功能：连接/脚本/用户的本地存储（tba.db）；自建表格的引擎（edict.db）；表 2 Ins 与列补全需要的表结构读取。
3. 用法：EDICT 导入时先做 WAL 检查与完整性校验、带时间戳备份，按表合并后原子切换内存实例；取列数用 PRAGMA table_info（该版本 Statement 无 getColumnCount，实测绕开）。

6 ExcelJS（Excel 写入）

1. 好处：功能齐全的成熟 xlsx 库，支持多工作表、列宽行高、样式控制。
2. 对应功能：2.6 的当前/全部结果 Excel 导出、单/分工作表模式、自动附加”查询脚本”信息页。
3. 用法：列宽计算按数字索引处理（中文列名会触发其列字母解析越界错误，实测修复）；信息页中多行 SQL 按折行逐行调整行高，保证打印可读。

7 csv-parse（CSV 解析）

1. 好处：久经考验的标准 CSV 解析器，各种转义与编码边角情况都由社区验证过。
2. 对应功能：表 2 Ins 与 EDICT 导入 CSV——引号内逗号、双引号转义、跨行字段、UTF-8 BOM 都能正确处理。
3. 用法：先解析成结构化行，再读目标表列元数据校验、按目标类型生成日期/数字字面量；GBK 文件先转码再进解析器。

8 Vue 3 + Pinia（界面框架与状态管理）

1. 好处：响应式 UI 降低界面同步成本；Pinia 集中管理状态，订阅变化即可实现持久化。
2. 对应功能：工作状态恢复（标签、草稿、筛选条件、面板布局，存储版本化到 v4 并自动迁移历史数据）；界面设置即时生效；全局页内对话框 ConfirmDialog/PromptDialog。
3. 用法：严格按”持久化态与运行态分离”设计——标签定义与草稿进存储，queryId/语句进度/结果等运行态放在不进存储的对象里按标签归档，后台完成的查询通过 queryId→标签映射只写回所属标签。