@hedeqiang/dsh-nl2sql 0.14.2 → 0.14.3

package/CHANGELOG.md

@@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.14.3] - 2026-11-13
+
+### Changed
+- **Cleaner bot reply cards:** intermediate queries the agent marks with `show: false`, and empty results when the answer has non-empty ones, are no longer shown (an empty probe of the wrong table read like "no such order").
+- **Buttons only where they help:** results looking up one order / id / hash, single rows and empty results get no "split by dimension", "details" or "pin to dashboard" buttons.
+- **Single records as field lists:** one-row results are shown as one "field: value" per line, with long identifiers in full (no truncation, no 万 / 亿 abbreviation of order numbers).
+- **Codes with meanings:** status / type codes are shown as `10（处理中）` when the column comment (e.g. `0=新建，10=处理中，11=交易失败`) or a knowledge column note defines them — in IM cards and tables.
+
 ## [0.14.2] - 2026-11-13
 
 ### Fixed
@@ -151,7 +159,8 @@ These features are tested with local databases and fake IM / Lark servers; real
 
 - Redesigned UI; Lark push (Markdown and native charts); access control, feedback loop, dashboard global filters; PostgreSQL / Elasticsearch, SSH tunnels, privacy settings, automatic overviews, scheduled reports; semantic layer, ER graph, scan guard, history and audit, dashboards; first version.
 
-[Unreleased]: https://github.com/hedeqiang/dsh-nl2sql/compare/v0.14.2...HEAD
+[Unreleased]: https://github.com/hedeqiang/dsh-nl2sql/compare/v0.14.3...HEAD
+[0.14.3]: https://github.com/hedeqiang/dsh-nl2sql/compare/v0.14.2...v0.14.3
 [0.14.2]: https://github.com/hedeqiang/dsh-nl2sql/compare/v0.14.1...v0.14.2
 [0.14.1]: https://github.com/hedeqiang/dsh-nl2sql/compare/v0.14.0...v0.14.1
 [0.14.0]: https://github.com/hedeqiang/dsh-nl2sql/compare/v0.13.1...v0.14.0

package/channels/lark.js

@@ -16,7 +16,7 @@
  */
 import { createHash, createHmac } from 'node:crypto'
 import { ChannelError, request } from './http.js'
-import { MD_TABLE, cellText, chartOption, chartable, dualAxis, escapeLarkMd, kpiText, isKpi, needsAttachment, num, oneLine, omittedNote, parseMdTable, renderChartPng, resultMeta } from './message.js'
+import { MD_TABLE, labelValue, cellText, chartOption, chartable, dualAxis, escapeLarkMd, kpiText, isKpi, needsAttachment, num, oneLine, omittedNote, parseMdTable, renderChartPng, resultMeta } from './message.js'
 
 export { ChannelError, ChannelError as ImError, chartOption, chartable, dualAxis, renderChartPng }
 
@@ -703,10 +703,12 @@ function tableElement(result, maxRows) {
     page_size: Math.min(10, Math.max(1, Math.min(maxRows, result.rows.length))),
     row_height: 'low',
     header_style: { background_style: 'grey', bold: true, text_size: 'normal' },
-    columns: cols.map((c, i) => ({ name: `c${i}`, display_name: c.name, data_type: c.kind === 'number' ? 'number' : 'text', ...(c.kind === 'number' ? { format: { separator: true } } : {}), width: 'auto' })),
+    columns: cols.map((c, i) => { const num = c.kind === 'number' && !c.labels; return { name: `c${i}`, display_name: c.name, data_type: num ? 'number' : 'text', ...(num ? { format: { separator: true } } : {}), width: 'auto' } }),
     // NULL / '' numbers stay empty (Number(null) would show 0); line breaks would break rows.
     rows: result.rows.slice(0, maxRows).map(r => Object.fromEntries(cols.flatMap((c, i) => {
       const v = r[i]
+      const labelled = labelValue(c, v)
+      if (labelled) return [[`c${i}`, oneLine(labelled)]]
       if (c.kind !== 'number') return [[`c${i}`, oneLine(cellText(v))]]
       if (v === null || v === undefined || v === '') return [] // empty cell, not 0
       return [[`c${i}`, Number.isFinite(Number(v)) ? Number(v) : oneLine(cellText(v))]]

package/channels/message.js

@@ -61,19 +61,40 @@ export function defangMd(s) {
  * A KPI-style result (one row) as `**col**：value ｜ …` Markdown. NULL shows as '—'.
  * `escape` is applied to data-derived text (column names and values).
  */
-export function kpiText(result, { separator = '　｜　', bold = true, escape = defangMd } = {}) {
+export function kpiText(result, { separator = '　｜　', bold = true, escape = defangMd, vertical } = {}) {
   const row = result.rows?.[0] ?? []
+  // A single record with several fields reads better as one field per line ("字段：值").
+  const listMode = vertical ?? (result.columns.length > 3 || result.columns.some((c, i) => String(row[i] ?? '').length > 24))
   return result.columns.map((c, i) => {
-    const raw = c.kind === 'number' ? fmtNum(row[i]) : cellText(row[i])
+    const labelled = labelValue(c, row[i])
+    // Long identifiers (order / trade numbers) are shown in full in list mode so they can be copied.
+    const raw = labelled ?? (c.kind === 'number' && !isCode(c, row[i]) ? fmtNum(row[i]) : cellText(row[i], listMode ? 200 : 80))
     const value = raw === '' ? '—' : escape(oneLine(raw))
     const name = escape(oneLine(c.name))
     return `${bold ? `**${name}**` : name}：${value}`
-  }).join(separator)
+  }).join(listMode ? '\n' : separator)
 }
 
-/** True when the result should be shown as KPI text rather than a table/chart. */
+/**
+ * `10` → `10（处理中）` when the column carries value labels (from the column comment or a
+ * knowledge note, attached by runQuery as `column.labels`). Returns undefined when unlabelled.
+ */
+export function labelValue(column, v) {
+  if (v === null || v === undefined || v === '' || !column?.labels) return undefined
+  const label = column.labels[String(v)]
+  return label ? `${v}（${label}）` : undefined
+}
+
+/** Numeric-looking ids / codes (order numbers, status codes) must not be abbreviated (万 / 亿). */
+function isCode(column, v) {
+  if (column?.labels) return true
+  const name = String(column?.name ?? '')
+  return /(^|_)(id|no|code|num|number|status|type|state|seq|hash)$|编号|单号|订单号|状态|类型/i.test(name) || (typeof v === 'string' && /^\d{12,}$/.test(v))
+}
+
+/** True when the result should be shown as KPI / field-list text rather than a table/chart. */
 export function isKpi(result) {
-  return result.chart?.type === 'kpi' || (result.rows.length === 1 && result.columns.length <= 6)
+  return result.chart?.type === 'kpi' || (result.rows.length === 1 && result.columns.length <= 12)
 }
 
 /** "12 行（已截断） · 已筛选：…" */

package/index.js

@@ -269,6 +269,7 @@ function registerTools(ctx, service) {
       properties: {
         sql: { type: 'string', description: 'The single read-only SQL statement.' },
         title: { type: 'string', description: 'Short human title for the result, in the user\'s language.' },
+        show: { type: 'boolean', description: 'IM bot answers only: false = an intermediate / exploratory query that should not be shown in the reply card (e.g. a lookup that found nothing, a probe of the wrong table). Default true.' },
         datasource: DATASOURCE_PARAM,
         chart: chartParam,
         confirmScan: { type: 'boolean', description: 'Set true only after a scan-guard refusal when the user accepts a full scan of a large table.' },
@@ -281,6 +282,7 @@ function registerTools(ctx, service) {
     presentCall: (args) => ({ card: 'generic', title: args?.title ? `查询：${args.title}` : '执行 SQL', kind: 'read' }),
     execute: wrap(async (args, exec) => {
       const result = await service.runQuery({ sql: args.sql, datasourceId: args.datasource, sessionId: exec.agent?.id, title: args.title, chart: args.chart, source: 'agent', confirmScan: Boolean(args.confirmScan) })
+      if (args.show === false) result.hidden = true
       return { model: service.modelView(result), display: displayMeta(result) }
     }),
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hedeqiang/dsh-nl2sql",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "description": "Ask MySQL, PostgreSQL, Elasticsearch and CSV/Excel in plain language inside DeepSeek Harness: charts, dashboards, alerts, and IM push and bots for Lark/Feishu, Telegram, WeCom and DingTalk.",
   "type": "module",
   "bin": {

package/service/bots.js

@@ -58,6 +58,29 @@ export function parseBotCommand(text) {
   return null
 }
 
+/**
+ * Results shown in a bot reply: drop ones the agent marked as intermediate (`show: false`),
+ * drop empty results when the answer has non-empty ones (an empty probe of the wrong table
+ * reads like "no such order"), keep at most the last 4.
+ */
+export function selectReplyResults(results) {
+  let list = results.filter(r => !r.hidden)
+  if (list.some(r => !r.error && r.rows?.length)) list = list.filter(r => r.error || r.rows?.length)
+  return list.slice(-4)
+}
+
+/**
+ * A point lookup: the WHERE pins a key column to one value (order no, id, hash…) and there is
+ * no GROUP BY. Splitting or pinning such a result to a dashboard makes no sense.
+ */
+export function isPointLookup(r, dialect) {
+  const parsed = parseSelect(r.baseSql ?? r.sql, { dialect })
+  if (!parsed || parsed.groupBy) return false
+  const where = String(parsed.where ?? '')
+  const keyEq = /(?:^|[^\w])`?(?:\w+\.)?`?(\w*(?:id|_no|no|order_?no|trade_?no|code|hash|uuid|sn|number)|id)`?\s*(?:=\s*'?[\w-]{4,}'?|in\s*\(\s*'?[\w-]{4,}'?\s*\))/i
+  return keyEq.test(where) || /'\d{10,}'|\b\d{12,}\b/.test(where)
+}
+
 function hasAggregate(r, dialect) {
   const parsed = parseSelect(r.baseSql ?? r.sql, { dialect })
   return Boolean(parsed?.select?.some(i => i.isAggregate))
@@ -384,7 +407,7 @@ export const methods = {
           ? `数据源：${ds.name}（群内已用「切换」指定，请只查询这个数据源）。`
           : `当前数据源：${ds.name}${routed?.ds ? '（按问题自动选择）' : ''}。该成员可用的数据源：\n${await this.datasourceCatalog(allowedDs)}\n请先判断问题属于哪个数据源：若不是当前数据源，先用 nl2sql_datasource action=use 切换再查询；在回答开头注明使用的数据源。`)
         : `数据源：${ds.name}。`
-      const prompt = `[${name}${where} · ${actor.name}${actor.role === 'viewer' ? ' · 只读成员' : ''}] ${text}\n\n（${dsLine}\n回答会以${name}消息发回该聊天：请用简洁的中文 Markdown 写结论，必要时附上查询结果；不要调用 nl2sql_send，也不要向用户提问——有歧义时说明你的假设后直接回答。${actor.role === 'viewer' ? '该成员是只读角色：只能用 nl2sql_metric 查询指标库，或复用 nl2sql_knowledge 中已验证的样例 SQL；不能自由编写 SQL。' : ''}）`
+      const prompt = `[${name}${where} · ${actor.name}${actor.role === 'viewer' ? ' · 只读成员' : ''}] ${text}\n\n（${dsLine}\n回答会以${name}消息发回该聊天：请用简洁的中文 Markdown 写结论，必要时附上查询结果（排查中间步骤、查错表或查不到数据的探索性查询请在 nl2sql_query 中设 show=false，回复卡片只展示支撑结论的结果）；不要调用 nl2sql_send，也不要向用户提问——有歧义时说明你的假设后直接回答。${actor.role === 'viewer' ? '该成员是只读角色：只能用 nl2sql_metric 查询指标库，或复用 nl2sql_knowledge 中已验证的样例 SQL；不能自由编写 SQL。' : ''}）`
       const requestId = platform === 'lark' ? `lark-${m.messageId}` : `${platform}-${m.chatId}-${m.messageId}`
       if (conv.sessionId && this.state.sessions[conv.sessionId] !== ds.id) { this.state.sessions[conv.sessionId] = ds.id; await this.save() }
       const turn = await this.runAgentTurn({ sessionId: conv.sessionId, title: `${name} · ${conv.chatName ?? actor.name}`, requestId, text: prompt, prepare, timeoutMs: 600000 })
@@ -393,7 +416,7 @@ export const methods = {
       let body = turn.text
       if (turn.reason === 'timeout') body = `${body ? `${body}\n\n` : ''}<font color='grey'>（查询超过 10 分钟仍未完成，已停止。请缩小范围后重试。）</font>`
       if (turn.reason === 'input-required') body = `${body ? `${body}\n\n` : ''}<font color='grey'>（需要在 Harness 中确认后才能继续，已取消本次回答。）</font>`
-      const results = turn.resultIds.map(id => this.lookupResult(id)).filter(Boolean).filter(r => { try { this.assertResultAccess(r, { ...actor, kind: platform }); return true } catch { return false } }).slice(-4)
+      const results = selectReplyResults(turn.resultIds.map(id => this.lookupResult(id)).filter(Boolean).filter(r => { try { this.assertResultAccess(r, { ...actor, kind: platform }); return true } catch { return false } }))
       // Buttons (拆分 / 为什么变化 / 明细 / 固定到看板) carry opaque tokens only.
       const shown = buttons ? await this.withResultActions(results, { actor, sessionId: conv.sessionId, channelId: m.channelId, platform, chatId: m.chatId, chatType: m.chatType, replyTo: m.messageId, depth: 0 }) : results
       let status = turn.reason === 'idle' ? 'ok' : 'error'
@@ -610,9 +633,14 @@ export const methods = {
       const role = actor?.role ?? 'analyst'
       const token = this.createActionToken({ resultId: result.resultId, sessionId, channelId, platform, chatId, chatType, replyTo, depth, ownerRole: role })
       const aggregate = hasAggregate(result, dialect)
+      const rows = result.rows?.length ?? 0
+      // Nothing to analyse in empty results; point lookups (one order / one id) and single rows
+      // are not dashboard material and have no dimension to split by.
+      if (rows === 0) return undefined
+      const lookup = isPointLookup(result, dialect)
       const buttons = []
       let select
-      if (aggregate) {
+      if (aggregate && rows > 1 && !lookup) {
         let dims = []
         try { dims = (await this.drillDimensions(result.resultId)).dimensions } catch {}
         const xName = result.chart?.x
@@ -623,8 +651,8 @@ export const methods = {
       const points = xi >= 0 ? result.rows.filter(r => r[xi] !== null && r[xi] !== undefined).length : 0
       const timeLike = xi >= 0 && (result.columns[xi].kind === 'time' || ['line', 'area'].includes(result.chart?.type))
       if (aggregate && timeLike && points >= 2) buttons.push({ text: '为什么变化', value: { a: 'why', t: token } })
-      if (xi >= 0 && points >= 1 && role !== 'viewer') buttons.push({ text: '明细', value: { a: 'detail', t: token } })
-      if (role === 'admin' || role === 'analyst') buttons.push({ text: '固定到看板', value: { a: 'pin', t: token } })
+      if (aggregate && !lookup && xi >= 0 && points >= 1 && role !== 'viewer') buttons.push({ text: '明细', value: { a: 'detail', t: token } })
+      if ((role === 'admin' || role === 'analyst') && !lookup && (aggregate || rows > 1)) buttons.push({ text: '固定到看板', value: { a: 'pin', t: token } })
       if (!select && !buttons.length) return undefined
       return { ...(select ? { select } : {}), buttons }
     } catch (error) {

package/service/query.js

@@ -9,7 +9,7 @@ import { admitSql, prepareSql, stripSql } from '../sql-guard.js'
 import { cacheKey } from '../store.js'
 import { createHash } from 'node:crypto'
 import { writeXlsx } from '../xlsx.js'
-import { RESULT_CACHE_LIMIT, SENSITIVE_NAME, SENSITIVE_RULES_VERSION, isCredentialToken, UserError, callContext, columnKind, fillChartHint, fmtNum, maskValue, newId, normalizeChart, suggestChart, summarize } from './shared.js'
+import { RESULT_CACHE_LIMIT, SENSITIVE_NAME, parseValueLabels, SENSITIVE_RULES_VERSION, isCredentialToken, UserError, callContext, columnKind, fillChartHint, fmtNum, maskValue, newId, normalizeChart, suggestChart, summarize } from './shared.js'
 
 export const methods = {
   // ---------------------------------------------------------------- query
@@ -146,7 +146,19 @@ export const methods = {
       })
     }
     for (const row of cells) for (const i of sensitive) row[i] = maskValue(res.columns[i].name, row[i])
-    const columns = res.columns.map((f, i) => ({ name: f.name, kind: columnKind(f, cells, i), ...(sensitive.has(i) ? { masked: true } : {}) }))
+    // Code → meaning for enum-like source columns (knowledge note first, then the column comment),
+    // so IM cards can show "10（处理中）" instead of a bare code.
+    const notes = this.knowledgeFor(ds.id).notes ?? {}
+    const labelsOf = (f) => {
+      if (!f.table || !f.column) return null
+      const col = schema?.tables.find(t => t.name === f.table)?.columns.find(c => c.name === f.column)
+      if (!col || col.roles?.includes('sensitive')) return null
+      return parseValueLabels(notes[`${f.table}.${f.column}`]) ?? parseValueLabels(col.comment)
+    }
+    const columns = res.columns.map((f, i) => {
+      const labels = sensitive.has(i) ? null : labelsOf(f)
+      return { name: f.name, kind: columnKind(f, cells, i), ...(sensitive.has(i) ? { masked: true } : {}), ...(labels ? { labels } : {}) }
+    })
     const suggested = suggestChart(columns, cells)
     const resultId = newId('r')
     const result = {

package/service/shared.js

@@ -84,6 +84,31 @@ export function maskValue(column, value) {
   return `${s.slice(0, keep)}${'*'.repeat(Math.max(4, s.length - keep * 2))}${s.slice(-keep)}`
 }
 
+/**
+ * Value labels from a column comment or a knowledge note, e.g.
+ *   '交易状态: 0=交易开始，10=处理中，11=交易失败'   → { '0': '交易开始', '10': '处理中', '11': '交易失败' }
+ *   '订单类型: 1withdraw,2deposit'                → { '1': 'withdraw', '2': 'deposit' }
+ *   '资产类型, 0: crypto, 1: rwa'                  → { '0': 'crypto', '1': 'rwa' }
+ * Only short codes (≤ 6 chars, digits or letters) mapped to short labels; needs ≥ 2 pairs.
+ */
+export function parseValueLabels(text) {
+  const src = String(text ?? '')
+  if (!src) return null
+  const out = {}
+  // A code is digits (or one letter); the label may follow directly ("1withdraw", "0内扣").
+  const re = /(?:^|[\s,，;；、:：(（/|])(-?\d{1,6})(?![0-9])\s*(?:=|:|：|-|→|\s)?\s*([^\s,，;；、:：()（）/|=0-9][^\s,，;；、:：()（）/|=]{0,23})/g
+  let m
+  while ((m = re.exec(src))) {
+    const [, code, label] = m
+    if (/^-?\d+$/.test(label) || label === code) continue
+    out[code] = label.replace(/[。.]$/, '')
+  }
+  // Prose like "version 2 of api 3" is not a mapping: require ≥ 2 pairs and most labels not plain English stop words.
+  const labels = Object.values(out)
+  if (labels.length < 2 || labels.filter(l => /^(of|and|or|to|in|on|the|a|an|is|for|at|by|with|位|个|天|次|分)$/i.test(l)).length * 2 >= labels.length) return null
+  return out
+}
+
 // ---------------------------------------------------------- schema analysis
 
 export const NUMERIC_TYPES = new Set(['tinyint', 'smallint', 'mediumint', 'int', 'integer', 'bigint', 'decimal', 'numeric', 'float', 'double', 'real'])