@hedeqiang/dsh-nl2sql 0.14.2 → 0.14.4

package/CHANGELOG.md

@@ -5,6 +5,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.14.4] - 2026-11-13
+
+### Added
+- Data freshness can be switched off, or hidden from the page only (**Manage → Data health → Settings**). When off, nothing is shown under results or in Schema, no scheduled checks run and the agent's `nl2sql_freshness` tool reports that it is off; "hide on page" keeps checks and notifications but removes the warning bars and the Schema panel. The Data health page keeps showing the data either way.
+
+## [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 +164,9 @@ 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.4...HEAD
+[0.14.4]: https://github.com/hedeqiang/dsh-nl2sql/compare/v0.14.3...v0.14.4
+[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/lib/client.js

@@ -17,6 +17,7 @@ window.__ModuleLoader__.load({
     // ------------------------------------------------------------ locale
 
     const zh = {
+      'fq.set.showInUi': "在页面上显示数据新鲜度（查询结果下的滞后提示、表结构页的新鲜度面板）",
       'mcp.client.claudeCode': 'Claude Code', 'mcp.client.cline': 'Cline', 'mcp.client.windsurf': 'Windsurf', 'mcp.client.codex': 'Codex CLI', 'mcp.client.gemini': 'Gemini CLI', 'mcp.client.zed': 'Zed', 'mcp.client.continue': 'Continue',
       'mcp.where.claudeCode': '在终端运行（HTTP 直连；下方为 stdio 桥接写法）。', 'mcp.where.cline': '写入 cline_mcp_settings.json（Cline 面板 → MCP Servers → Configure）。', 'mcp.where.windsurf': '写入 Windsurf 的 mcp_config.json（Cascade → MCP → 打开配置文件）。', 'mcp.where.codex': '写入 ~/.codex/config.toml（或项目的 .codex/config.toml）。', 'mcp.where.gemini': '写入 ~/.gemini/settings.json 或项目的 .gemini/settings.json。', 'mcp.where.zed': '写入 Zed 的 settings.json。', 'mcp.where.continue': '保存为工作区 .continue/mcpServers/nl2sql.yaml。',
       'mcp.test': '测试连接', 'mcp.testOk': '连接正常：发现 {n} 个工具。', 'mcp.testFail': '连接失败：{error}', 'mcp.testFailSteps': '连接测试未通过：',
@@ -80,7 +81,7 @@ window.__ModuleLoader__.load({
       "fq.admin.qOff": "每日质量巡检已关闭",
       "fq.admin.noDs": "请先添加数据源",
       "fq.set.title": "设置",
-      "fq.set.fEnabled": "定时检查数据新鲜度",
+      "fq.set.fEnabled": "启用数据新鲜度（定时检查、滞后通知、Agent 回答近期数据时的提醒）；关闭后页面上也不再显示",
       "fq.set.qEnabled": "每日数据质量巡检",
       "fq.set.interval": "新鲜度检查间隔（分钟）",
       "fq.set.time": "质量巡检时间",
@@ -1178,6 +1179,7 @@ window.__ModuleLoader__.load({
       'policy.tablesLabel': '可访问的表',
     }
     const en = {
+      'fq.set.showInUi': "Show data freshness on the page (stale-data bars under results, the freshness panel in Schema)",
       'mcp.client.claudeCode': 'Claude Code', 'mcp.client.cline': 'Cline', 'mcp.client.windsurf': 'Windsurf', 'mcp.client.codex': 'Codex CLI', 'mcp.client.gemini': 'Gemini CLI', 'mcp.client.zed': 'Zed', 'mcp.client.continue': 'Continue',
       'mcp.where.claudeCode': 'Run in a terminal (HTTP; the stdio bridge variant is below).', 'mcp.where.cline': 'Add to cline_mcp_settings.json (Cline panel → MCP Servers → Configure).', 'mcp.where.windsurf': 'Add to Windsurf\'s mcp_config.json (Cascade → MCP → open config file).', 'mcp.where.codex': 'Add to ~/.codex/config.toml (or the project\'s .codex/config.toml).', 'mcp.where.gemini': 'Add to ~/.gemini/settings.json or the project\'s .gemini/settings.json.', 'mcp.where.zed': 'Add to Zed\'s settings.json.', 'mcp.where.continue': 'Save as .continue/mcpServers/nl2sql.yaml in the workspace.',
       'mcp.test': 'Test connection', 'mcp.testOk': 'Connected: {n} tools discovered.', 'mcp.testFail': 'Connection failed: {error}', 'mcp.testFailSteps': 'Connection test failed:',
@@ -1241,7 +1243,7 @@ window.__ModuleLoader__.load({
       "fq.admin.qOff": "Daily quality patrol is off",
       "fq.admin.noDs": "Add a data source first",
       "fq.set.title": "Settings",
-      "fq.set.fEnabled": "Check data freshness on a schedule",
+      "fq.set.fEnabled": "Enable data freshness (scheduled checks, stale-data notifications, warnings in answers about recent data); when off, nothing is shown on the page either",
       "fq.set.qEnabled": "Daily data quality patrol",
       "fq.set.interval": "Freshness check interval (min)",
       "fq.set.time": "Quality patrol time",
@@ -6630,19 +6632,21 @@ window.__ModuleLoader__.load({
           const key = `${datasourceId}\u0000${sql ?? ''}`
           const hit = map.get(key)
           if (hit && Date.now() - hit.at < TTL) return hit.promise
-          const promise = call('freshnessFor', { datasourceId, ...(sql ? { sql } : {}) })
+          const promise = call('freshnessFor', { datasourceId, panel: true, ...(sql ? { sql } : {}) })
           map.set(key, { at: Date.now(), promise })
           promise.catch(() => map.delete(key))
           return promise
         },
         async refresh(datasourceId) {
-          const v = await call('freshnessFor', { datasourceId, refresh: true })
+          const v = await call('freshnessFor', { datasourceId, refresh: true, panel: true })
           for (const k of [...map.keys()]) if (k.startsWith(`${datasourceId}\u0000`)) map.delete(k)
           map.set(`${datasourceId}\u0000`, { at: Date.now(), promise: Promise.resolve(v) })
           rev++
           for (const f of subs) f()
           return v
         },
+        /** Drop everything (e.g. after the show / enable settings change) and re-render subscribers. */
+        reset() { map.clear(); rev++; for (const f of subs) f() },
         subscribe(f) { subs.add(f); return () => subs.delete(f) },
         rev: () => rev,
       }
@@ -6691,6 +6695,7 @@ window.__ModuleLoader__.load({
         fqCache.get(dsId, sql).then(v => alive && setView(v), () => {})
         return () => { alive = false }
       }, [dsId, sql, rev])
+      if (view?.disabled) return null
       const stale = (view?.tables ?? []).filter(x => x.stale)
       if (!stale.length) return null
       return h('div', { className: 'n2s-fq-bar', role: 'status' },
@@ -6719,7 +6724,7 @@ window.__ModuleLoader__.load({
         return () => { alive = false }
       }, [ds?.id, rev])
       const v = state.value
-      if (!ds || state.error || !v || !v.tables?.length) return null
+      if (!ds || state.error || !v || v.disabled || !v.tables?.length) return null
       const stale = v.tables.filter(x => x.stale).length
       const warn = v.tables.filter(x => x.status === 'warn').length
       const expanded = open ?? stale > 0
@@ -6786,6 +6791,7 @@ window.__ModuleLoader__.load({
           const { overrides: _o, ...freshness } = form.freshness
           const out = await call('saveHealthSettings', { freshness: { ...freshness, intervalMin: Number(freshness.intervalMin), staleHours: Number(freshness.staleHours), channelId: freshness.channelId || null }, quality: { ...form.quality, dropPoints: Number(form.quality.dropPoints), channelId: form.quality.channelId || null } })
           setForm(structuredClone(out))
+          fqCache.reset()
           notify(t('fq.saved'), 'ok')
           onSaved?.()
         } catch (e) { notifyError(e) }
@@ -6793,6 +6799,7 @@ window.__ModuleLoader__.load({
       return h('div', { className: 'n2s-card' },
         h('div', { className: 'n2s-form' },
           h('label', { className: 'n2s-check' }, h('input', { type: 'checkbox', checked: Boolean(form.freshness.enabled), onChange: e => setF('enabled', e.target.checked) }), t('fq.set.fEnabled')),
+          h('label', { className: 'n2s-check' }, h('input', { type: 'checkbox', checked: form.freshness.showInUi !== false && Boolean(form.freshness.enabled), disabled: !form.freshness.enabled, onChange: e => setF('showInUi', e.target.checked) }), t('fq.set.showInUi')),
           h('label', { className: 'n2s-check' }, h('input', { type: 'checkbox', checked: Boolean(form.quality.enabled), onChange: e => setQ('enabled', e.target.checked) }), t('fq.set.qEnabled')),
           h('label', { className: 'n2s-field' }, h('span', null, t('fq.set.interval')), h('input', { className: 'n2s-input', type: 'number', min: 5, max: 1440, value: form.freshness.intervalMin, onChange: e => setF('intervalMin', e.target.value) })),
           h('label', { className: 'n2s-field' }, h('span', null, t('fq.set.time')), h('input', { className: 'n2s-input', type: 'time', value: form.quality.time, onChange: e => setQ('time', e.target.value) })),
@@ -6807,7 +6814,7 @@ window.__ModuleLoader__.load({
 
     function HealthFreshnessTable({ t, dsId }) {
       const rev = useFqRev()
-      const fr = useAsync(() => (dsId ? fqCache.get(dsId) : null), [dsId, rev])
+      const fr = useAsync(() => (dsId ? call('freshnessFor', { datasourceId: dsId }) : null), [dsId, rev])
       const settings = useAsync(() => call('healthSettings'), [dsId, rev])
       const events = useAsync(() => (dsId ? call('freshnessEvents', { datasourceId: dsId, limit: 10 }) : []), [dsId, rev])
       const [busy, setBusy] = useState(false)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hedeqiang/dsh-nl2sql",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "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/freshness.js

@@ -19,7 +19,8 @@ import { UserError, lastDailySlot, newId } from './shared.js'
 
 // ------------------------------------------------------------------ constants
 
-export const FRESHNESS_DEFAULTS = { enabled: true, intervalMin: 30, staleHours: 24, overrides: {}, channelId: null }
+// enabled: scheduled checks + notifications + the agent tool; showInUi: warning bars under results and the schema panel.
+export const FRESHNESS_DEFAULTS = { enabled: true, showInUi: true, intervalMin: 30, staleHours: 24, overrides: {}, channelId: null }
 export const QUALITY_DEFAULTS = { enabled: false, time: '06:30', channelId: null, dropPoints: 10, maxTableRows: 5000000, maxTables: 60 }
 const DATE_TYPES = new Set(['date', 'datetime', 'timestamp', 'timestamptz'])
 const NUM_TYPES = new Set(['tinyint', 'smallint', 'mediumint', 'int', 'integer', 'bigint', 'decimal', 'numeric', 'float', 'double', 'real'])
@@ -271,6 +272,7 @@ export const methods = {
     if (freshness) {
       const s = this.freshnessState().settings
       if (freshness.enabled !== undefined) s.enabled = Boolean(freshness.enabled)
+      if (freshness.showInUi !== undefined) s.showInUi = Boolean(freshness.showInUi)
       if (freshness.intervalMin !== undefined) s.intervalMin = Math.round(intIn(freshness.intervalMin, 5, 1440, 'intervalMin'))
       if (freshness.staleHours !== undefined) s.staleHours = intIn(freshness.staleHours, 0.25, 24 * 90, 'staleHours')
       if (freshness.channelId !== undefined) s.channelId = channel(freshness.channelId)
@@ -422,9 +424,12 @@ export const methods = {
   },
 
   /** RPC: stored freshness (computed on first use or when refresh); `sql` narrows to referenced tables. */
-  async freshnessFor({ datasourceId, refresh = false, sql } = {}) {
+  async freshnessFor({ datasourceId, refresh = false, sql, panel = false } = {}) {
     const ds = this.requireDatasource(datasourceId ?? this.state.current)
     const f = this.freshnessState()
+    // Page panels (result bars, schema panel) ask with panel: true; when the feature or its
+    // page display is off they get nothing and no query runs.
+    if (panel && (!f.settings.enabled || f.settings.showInUi === false)) return { datasourceId: ds.id, disabled: true, tables: [] }
     let store = f[ds.id]
     if (refresh || !store) {
       if (refresh) store = await this.withJobLock(`freshness:${ds.id}`, () => this.refreshFreshness(ds))
@@ -737,6 +742,7 @@ export const FEATURE = {
       presentCall: (args) => ({ card: 'generic', title: args?.tables?.length ? `数据新鲜度 ${args.tables.join(', ')}` : '数据新鲜度', kind: 'read' }),
       execute: async (args, exec) => {
         try {
+          if (!service.freshnessState().settings.enabled) return { disabled: true, message: 'Data freshness checks are turned off by the administrator (Data Q&A → Manage → Data health). Answer without freshness warnings.' }
           return await service.freshnessForSession({ sessionId: exec?.agent?.id, datasource: args?.datasource, tables: args?.tables })
         } catch (error) {
           throw error instanceof UserError ? new Error(error.message) : 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'])