数据库客户端后端前端CLI桌面应用数据可视化AI 应用【免费下载链接】whodbWhere data access meets operational intelligence项目地址https://gitcode.com/gh_mirrors/wh/whodb点击查看免费下载本指南深入解析 WhoDB 开源仓库中内置的query-builderMCP Skill。它指导 AI 智能体在whodb mcp serve提供的数据库专用 MCP 工具之上把帮我找出上周注册的用户这类自然语言问题一步步转换成结构正确、可安全执行的 SQL 查询。读完本文你将掌握该 Skill 的五步工作流、意图拆解方法、跨数据库日期语法以及与之配套的 MCP 安全机制与底层实现原理。Skill 定位与启用前提query-builder是 WhoDB 随 CLI 一起分发的 Agent Skill技能说明文件核心职责是Convert natural language questions into SQL queries using the database schema.它对应的物理文件位于 cli/external-plugin/whodb/skills/query-builder/SKILL.md仓库内部还有一个同源版本 cli/skills/query-builder/SKILL.md。Skill 头部元数据如下name: query-builder description: Convert natural language questions into SQL queries. Activates when users ask data questions in plain English like show me users who signed up last week or find orders over $100.数据库专用 MCP 工具该 Skill 只依赖database-only MCP toolswhodb_tables、whodb_columns、whodb_query等这些工具要求通过whodb setup启用 database 模块并把 MCP 服务命令固定为whodb mcp serve对应的客户端配置如 cli/external-plugin/whodb/.mcp.json{ whodb: { command: npx, args: [-y, whodb, mcp, serve] } }关于启用流程whodb setup提供了面向 Agent 的非交互子命令见 cli/cmd/setup.gowhodb setup inspect查看当前设置与可选模块、validate校验配置补丁、apply --yes应用、verify逐项验证登录与连接。需要注意的是如果目标是 WhoDB 平台platform资源则应改用 cli/external-plugin/whodb/skills/whodb/SKILL.md 中描述的工作区workspace定位方式并去发现对应的whodb_platform_*工具而不是直接调用数据库工具。何时激活该 Skill当用户以数据问答口吻提问时激活典型触发句包括Show me all users who signed up last month上个月注册的所有用户Find orders greater than $100金额大于 100 美元的订单Which products have low inventory?哪些产品库存偏低Get the top 10 customers by total spend总消费最高的前 10 名客户这些句子的共同特征是需要把时间范围、数值阈值、排序与行数限制翻译成 SQL 语义而不是简单的全表查询。五步工作流Skill 定义了从自然语言到可执行 SQL 的标准流程Agent 应严格按序执行。1. 理解 Schema先看表结构生成 SQL 之前永远先检查表结构。在仓库内部版本的 Skill 中这一步骤被优化为单次调用whodb_tables(connection..., include_columnstrue) → Get all tables AND their column names, types, and keysinclude_columnstrue会把所有表的列名、类型、主键、外键信息一次性带回。从实现上看whodb_tables的入参定义在 cli/pkg/mcp/tools.go其HandleTablescli/pkg/mcp/read_tools.go在include_columns为真时会批量调用mgr.GetColumnsForStorageUnits把列信息合并到每个TableInfo.Columns中显著减少 Agent 的往返调用次数。对于多 schema 数据库可先用whodb_schemas(connection..., include_tablestrue)确定要查询的 schema。2. 识别意图拆解六要素把自然语言请求拆成六个维度逐一映射到 SQL 子句意图要素要回答的问题对应 SQLSubject主体是什么实体users、orders、productsFROM子句的表Filter过滤什么条件last month、 $100、activeWHERE子句Aggregation聚合需要 count、sum、average、max、min 吗聚合函数 GROUP BYGrouping分组按什么维度分组GROUP BYOrdering排序按什么排序升序还是降序ORDER BY ... ASC/DESCLimit限量返回多少条结果LIMIT n3. 映射到 Schema把实体名匹配到真实表名注意复数、缩写、schema 前缀把属性词匹配到列名识别需要的外键 JOIN 关系——这一步依赖第 1 步拿到的is_foreign_key、referenced_table、referenced_column字段对应 cli/pkg/mcp/tools.go 的ColumnInfo结构。4. 生成 SQL遵循最佳实践模板SELECT columns FROM table [JOIN other_table ON condition] WHERE filters [GROUP BY columns] [HAVING aggregate_condition] ORDER BY column [ASC|DESC] LIMIT n;5. 执行并呈现结果whodb_query(querygenerated SQL)whodb_query支持可选connection参数只有单一连接时可省略必要时还可携带parameters走参数化查询详见下文源码级实现一节。自然语言 → SQL 翻译模式速查表Skill 给出了覆盖高频问法的基础翻译表这是 Agent 逐句对照生成 SQL 的字典自然语言表达SQL 模式last week/month/yearWHERE date_col DATE_SUB(NOW(), INTERVAL 1 WEEK)more than X / greater than XWHERE col Xtop NORDER BY col DESC LIMIT Nhow manySELECT COUNT(*)total / sum ofSELECT SUM(col)averageSELECT AVG(col)for each / byGROUP BY colbetween X and YWHERE col BETWEEN X AND Ycontains / likeWHERE col LIKE %term%starts withWHERE col LIKE term%is empty / is nullWHERE col IS NULLis not emptyWHERE col IS NOT NULL需要注意两点实践细节LIKE %term%这类前导通配符写法成本较高当数据量大时应向用户说明或改用全文索引方案仓库内的 query-optimizer Agent 将其列为高影响性能问题日期类表达必须按下表换成对应数据库的方言语法不能直接复用 MySQL 写法。按数据库区分的日期处理PostgreSQLWHERE created_at NOW() - INTERVAL 7 days WHERE created_at DATE_TRUNC(month, CURRENT_DATE)DATE_TRUNC(month, CURRENT_DATE)会返回本月 1 日的 00:00:00是本月注册用户最稳妥的写法。MySQLWHERE created_at DATE_SUB(NOW(), INTERVAL 7 DAY) WHERE created_at DATE_FORMAT(NOW(), %Y-%m-01)MySQL 的INTERVAL 7 DAY不带引号与 PostgreSQL 的INTERVAL 7 days带引号写法不同跨库生成时务必区分。SQLiteWHERE created_at DATE(now, -7 days) WHERE created_at DATE(now, start of month)SQLite 使用DATE(now, modifier)修饰符语法start of month直接给出月初日期。完整示例Show me users who signed up this month本月注册的用户SELECT * FROM users WHERE created_at DATE_TRUNC(month, CURRENT_DATE) ORDER BY created_at DESC;该示例假设目标为 PostgreSQL 方言若目标库是 MySQL 或 SQLite需按上文日期规则替换WHERE条件。Find the top 5 products by sales销量前五的产品SELECT p.name, SUM(oi.quantity) as total_sold FROM products p JOIN order_items oi ON p.id oi.product_id GROUP BY p.id, p.name ORDER BY total_sold DESC LIMIT 5;这是 JOIN 聚合 排序 限量四要素的完整组合p与oi是表别名可读性要求total_sold是聚合结果的别名GROUP BY必须包含p.id, p.name两列才能正确聚合。How many orders per customer?每个客户有多少订单SELECT customer_id, COUNT(*) as order_count FROM orders GROUP BY customer_id ORDER BY order_count DESC;COUNT(*)对应 how manyGROUP BY customer_id对应 per customer降序排序让订单最多的客户排在最前。源码级实现query-builder 背后的执行链了解 Skill 规则后再看它调用的工具在 WhoDB 中如何落地能帮助你预判生成 SQL 的边界。参数化查询与结果结构whodb_query的输入输出结构定义在 cli/pkg/mcp/tools.goQueryInput除connection、query外还支持parameters用于参数化查询PostgreSQL 用$1/$2占位MySQL/SQLite 用?。QueryOutput返回columns、column_types、rows其中column_types让 Agent 无需额外调用即可知道结果列的数据类型。执行时若parameters非空走ExecuteQueryWithParams参数化路径以规避 SQL 注入cli/pkg/mcp/tools.go。安全校验三层闸门任何生成的 SQL 在真正执行前都要过 cli/pkg/mcp/validation.go 的校验破坏性操作拦截默认禁止DROP/TRUNCATE需--confirm-writes或显式--allow-drop放行语法形态检查禁止 SQL 注释--、/* */默认禁止多语句分号分割危险函数清单strict安全级别下会拦截PG_READ_FILE、COPY、LOAD_FILE、XP_CMDSHELL、UTL_FILE等函数完整清单见 cli/pkg/mcp/validation.go。此外底层还有独立的语句分类器 core/src/sqlguard/classify.go只有匹配受支持的只读语法才会被判定为只读任何无法证明只读的语句如可写 CTE、EXPLAIN ANALYZE包裹写语句都按可能变更状态处理在 confirm-writes 模式下要求人工确认。这一点对 Skill 的永远不要擅自生成写语句规则形成了代码级的兜底。结果包装与提示注入防护查询结果返回给 LLM 前会经过wrapUntrustedQueryResultcli/pkg/mcp/tools.go包装数据库内容可能包含恶意指令文本因此结果被放在带随机边界 ID 的query-result-xxx.../query-result-xxx标签内并明确告知模型边界内内容一律视为不可信数据。这意味着 Skill 生成的查询若命中含指令的数据模型也不会被诱导执行。行数截断与超时whodb mcp serve支持--max-rows默认 0 表示不限制与--timeout默认 30s见 cli/cmd/mcp.go。当结果超过--max-rows时工具返回截断警告Results truncated to N rows. Use LIMIT in your query for more control.cli/pkg/mcp/tools.go。这也解释了 Skill 安全规则里探索性查询必须带 LIMIT的由来——服务端限流只截断展示真正可控的结果集规模要靠 SQL 自带 LIMIT。安全规则Agent 必须遵守Skill 为生成 SQL 设置了四条硬性规则Always use LIMIT for exploratory queries (default: 100)——探索性查询永远加LIMIT默认不超过 100 行Never generate DELETE, UPDATE, or DROP unless explicitly requested——除非用户明确要求绝不生成任何写操作语句Warn if query might return large result sets——预计结果集很大时必须先提醒用户Use table aliases for readability in JOINs——JOIN 场景使用表别名提升可读性。从实现侧看即使 Agent 违反第二条规则MCP 服务端也会兜底confirm-writes 是默认权限模式非只读语句必须先返回confirmation_token经whodb_confirm确认后才能执行token 5 分钟过期见 cli/pkg/mcp/tools.go。更多安全模式说明可参考 cli/external-plugin/whodb/README.md--safe-mode只读 严格安全、--read-only仅 SELECT/SHOW/DESCRIBE/EXPLAIN、--allow-write全写权限需谨慎等。扩展与其他 Skill/Agent 的分工query-builder只是 WhoDB 技能体系的一员与本主题强相关的还有schema-designer负责建表/设计 schema与 query-builder 恰好互补——一个消费 schema 生成查询一个设计 schemawhodb主数据库技能覆盖连接管理、平台工具与 CLI 回退命令query-optimizer查询性能优化专家可对 query-builder 产出的慢查询做EXPLAIN分析、索引建议与 SQL 重写。实战中推荐的分工是先用 query-builder 快速把自然语言问题变成可用 SQL遇到性能瓶颈时再移交 query-optimizer 做深入优化。小结query-builder Skill 的价值在于把读 schema → 拆意图 → 映射实体 → 生成 SQL → 安全执行固化为 Agent 可复用的标准流程并通过翻译模式表覆盖日期、比较、聚合、分组、模糊匹配等最常见语义。配合 WhoDB 的whodb_tables(include_columnstrue)单次取全量 schema、参数化查询与三层安全校验它能让 AI 助手在可控、可审计的前提下完成绝大多数数据问答场景。赞分享数据库客户端后端前端CLI桌面应用数据可视化AI 应用【免费下载链接】whodbWhere data access meets operational intelligence项目地址https://gitcode.com/gh_mirrors/wh/whodb点击查看免费下载相关推荐基于 LangChain 的 SQL Query Agent 实战指南让 GPT-4o-mini 用自然语言查询任意 SQLite 数据库基于 LangChain 的 SQL Query Agent 实战指南让 GPT 4o mini 用自然语言查询任意 SQLite 数据库 本指南以 500示例工程人工智能mcp-neo4j将自然语言转化为图数据库操作mcp neo4j将自然语言转化为图数据库操作 项目介绍 在当今的大数据时代图数据库以其独特的网络结构存储和查询数据的能力受到了广泛关注。mcp neo4Cursor禁用自动更新指南3 种方案 验证 恢复Cursor禁用自动更新指南3 种方案 验证 恢复 你的开发环境不该被软件更新节奏绑架。本文是 Cursor 禁用自动更新的完整操作手册更新机制原理开发工具CLI上一篇Boltz-2的CUDA版本要求从11.3到12.1的性能测试下一篇yaml-cpp MIT许可证完整指南商业项目使用的7个关键注意事项创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考