@hedeqiang/dsh-nl2sql 0.11.1 → 0.12.0

package/channels/lark.js

@@ -1,5 +1,5 @@
 /**
- * Lark / Feishu channel adapter (see docs/CHANNELS.md).
+ * Lark / Feishu channel adapter (see docs/channels.md).
  *
  * Kinds:
  *   - lark_webhook: a group custom bot (webhook URL + optional signing secret).
@@ -16,7 +16,7 @@
  */
 import { createHash, createHmac } from 'node:crypto'
 import { ChannelError, request } from './http.js'
-import { MD_TABLE, cellText, chartOption, chartable, dualAxis, kpiText, isKpi, num, parseMdTable, renderChartPng, resultMeta } from './message.js'
+import { MD_TABLE, cellText, chartOption, chartable, dualAxis, kpiText, isKpi, needsAttachment, num, omittedNote, parseMdTable, renderChartPng, resultMeta } from './message.js'
 
 export { ChannelError, ChannelError as ImError, chartOption, chartable, dualAxis, renderChartPng }
 
@@ -677,6 +677,18 @@ async function uploadImage(channel, secrets, png) {
   return json.data.image_key
 }
 
+/** Upload a file (≤ 30 MB) for a file message; returns file_key. https://open.feishu.cn/document/server-docs/im-v1/file/create */
+async function uploadFile(channel, secrets, buf, fileName, fileType = 'xls') {
+  const token = await pushToken(channel, secrets)
+  const form = new FormData()
+  form.set('file_type', fileType)
+  form.set('file_name', fileName)
+  form.set('file', new Blob([buf], { type: 'application/octet-stream' }), fileName)
+  const { status, json } = await request(`${hostFor(channel)}/open-apis/im/v1/files`, { method: 'POST', headers: { authorization: `Bearer ${token}` }, body: form, timeoutMs: 60000, label: '飞书' })
+  if (json.code !== 0) throw larkPushError(json, status)
+  return json.data.file_key
+}
+
 // ===========================================================================
 // Cards (JSON 2.0)
 // ===========================================================================
@@ -687,6 +699,7 @@ function tableElement(result, maxRows) {
   const cols = result.columns.slice(0, 8)
   return {
     tag: 'table',
+    // page_size is 1..10 per the card spec; more rows are paged in the client.
     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' },
@@ -820,7 +833,7 @@ export function actionElement(spec) {
  * Build a JSON 2.0 card from an OutboundMessage.
  * Results may carry `imageKey` (uploaded PNG) and `actions` (ActionSpec; legacy name `cardActions`).
  */
-export function buildCard(message, { maxRows = 10, charts = true, actions = true } = {}) {
+export function buildCard(message, { maxRows = 50, charts = true, actions = true } = {}) {
   const elements = [...markdownElements(message.text)]
   let tables = elements.filter(e => e.tag === 'table').length
   let chartCount = 0
@@ -844,8 +857,12 @@ export function buildCard(message, { maxRows = 10, charts = true, actions = true
     } else if (tables < 5) {
       elements.push(tableElement(r, maxRows))
       tables++
+      const note = omittedNote(r, Math.min(maxRows, r.rows.length), { attached: Boolean(r.attached) })
+      if (note) elements.push({ tag: 'markdown', content: `<font color='grey'>${note}</font>`, text_size: 'notation' })
     } else {
       elements.push({ tag: 'markdown', content: r.rows.slice(0, 5).map(row => row.slice(0, 6).map(v => cellText(v)).join(' | ')).join('\n') })
+      const note = omittedNote(r, Math.min(5, r.rows.length), { attached: Boolean(r.attached) })
+      if (note) elements.push({ tag: 'markdown', content: `<font color='grey'>${note}</font>`, text_size: 'notation' })
     }
     const spec = r.actions ?? r.cardActions
     if (spec && actions) {
@@ -863,7 +880,7 @@ export function buildCard(message, { maxRows = 10, charts = true, actions = true
   }
   // Card bodies are limited to ~30 KB: shrink tables/charts until it fits.
   const size = Buffer.byteLength(JSON.stringify(card))
-  if (size > CARD_LIMIT && maxRows > 3) return buildCard(message, { maxRows: Math.max(3, Math.floor(maxRows / 2)), charts, actions })
+  if (size > CARD_LIMIT && maxRows > 5) return buildCard(message, { maxRows: Math.max(5, Math.floor(maxRows / 2)), charts, actions })
   if (size > CARD_LIMIT && charts) return buildCard(message, { maxRows, charts: false, actions })
   if (size > CARD_LIMIT) {
     card.body.elements = elements.filter(e => e.tag !== 'table')
@@ -915,6 +932,7 @@ export async function sendMessage(channel, secrets, message) {
     }
     results.push(r)
   }
+  if (channel.type === 'lark_app' && message.attachment?.buffer) for (let i = 0; i < results.length; i++) if (message.attachment.resultIndexes?.includes(i)) results[i] = { ...results[i], attached: true }
   const card = buildCard({ ...message, results }, { charts: message.chartMode !== 'image' && message.chartMode !== 'table' })
   if (channel.type === 'lark_webhook') {
     if (!secrets.webhookUrl) throw new ChannelError('im/config', '缺少 Webhook 地址')
@@ -944,7 +962,17 @@ export async function sendMessage(channel, secrets, message) {
     if (json.code !== 0 && !fatal.includes(json.code) && card.body.elements.some(e => e.tag === 'chart')) ({ status, json } = await send(buildCard({ ...message, results }, { charts: false })))
     if (json.code !== 0 && !fatal.includes(json.code)) ({ status, json } = await send(legacyCard(card)))
     if (json.code !== 0) throw larkPushError(json, status)
-    return { messageId: json.data?.message_id, images }
+    // Full data as an Excel file message after the card (app bots only; webhooks cannot send files).
+    let files = 0
+    if (message.attachment?.buffer) {
+      try {
+        const fileKey = await uploadFile(channel, secrets, message.attachment.buffer, message.attachment.fileName)
+        const fr = await postJson(url, { receive_id: channel.receiveId, msg_type: 'file', content: JSON.stringify({ file_key: fileKey }) }, { authorization: `Bearer ${token}` })
+        if (fr.json.code === 0) files++
+        else message.attachmentError = larkPushError(fr.json, fr.status).message
+      } catch (error) { message.attachmentError = error.message }
+    }
+    return { messageId: json.data?.message_id, images, files, ...(message.attachmentError ? { warning: `完整数据附件发送失败：${message.attachmentError}` } : {}) }
   }
   throw new ChannelError('im/config', `不支持的渠道类型：${channel.type}`)
 }
@@ -1104,7 +1132,7 @@ export const kinds = [
       { key: 'webhookUrl', label: { zh: 'Webhook 地址', en: 'Webhook URL' }, type: 'secret', secret: true, required: true, placeholder: 'https://open.feishu.cn/open-apis/bot/v2/hook/…', pattern: WEBHOOK_RE.source },
       { key: 'signSecret', label: { zh: '签名密钥', en: 'Signing secret' }, type: 'secret', secret: true, help: { zh: '机器人开启「签名校验」时填写', en: 'Only when signature verification is enabled' } },
     ],
-    capabilities: { push: true, markdown: 'full', charts: 'native', chartModes: ['native', 'table'], tables: 'native', buttons: false, bot: false, listTargets: false, mentionAll: true, maxMessageBytes: 28000 },
+    capabilities: { push: true, markdown: 'full', charts: 'native', chartModes: ['native', 'table'], tables: 'native', tableRows: 50, files: false, buttons: false, bot: false, listTargets: false, mentionAll: true, maxMessageBytes: 28000 },
     setupSteps: WEBHOOK_SETUP,
     validate(input, existing) {
       const config = {}
@@ -1141,7 +1169,7 @@ export const kinds = [
       ] },
       { key: 'receiveId', label: { zh: '接收者 ID', en: 'Receiver ID' }, type: 'text', required: true, placeholder: 'oc_…', target: true, help: { zh: '推送目标；选择群时可点「列出群聊」', en: 'Push target; use "List chats" to pick a chat' } },
     ],
-    capabilities: { push: true, markdown: 'full', charts: 'native', chartImages: true, chartModes: ['native', 'image', 'table'], tables: 'native', buttons: true, bot: true, listTargets: true, mentionAll: true, maxMessageBytes: 28000 },
+    capabilities: { push: true, markdown: 'full', charts: 'native', chartImages: true, chartModes: ['native', 'image', 'table'], tables: 'native', tableRows: 50, files: true, buttons: true, bot: true, listTargets: true, mentionAll: true, maxMessageBytes: 28000 },
     setupSteps: APP_SETUP,
     validate(input, existing) {
       const c = input.config ?? {}

package/channels/message.js

@@ -3,7 +3,7 @@
  *
  * OutboundMessage = { title, text?, results?, footer?, includeSql?, chartMode?, mentionAll?, template? }
  * ResultBlock     = { title, columns:[{name,kind}], rows, rowCount, truncated, chart, sql?, filters?, error?, actions? }
- * (see docs/CHANNELS.md)
+ * (see docs/channels.md)
  */
 import * as echarts from 'echarts'
 import { Resvg } from '@resvg/resvg-js'
@@ -42,6 +42,23 @@ export function isKpi(result) {
 }
 
 /** "12 行（已截断） · 已筛选：…" */
+/**
+ * One line telling the reader how much of a result the message shows, or ''
+ * when everything is shown. `attached` = a full-data file follows.
+ */
+export function omittedNote(result, shown, { attached = false } = {}) {
+  const total = result.rowCount ?? result.rows?.length ?? 0
+  if (shown >= total && !result.truncated) return ''
+  const base = shown < total ? `共 ${total} 行，消息中显示前 ${shown} 行` : `查询结果已按行数上限截断（${total} 行）`
+  return attached ? `${base}，完整数据见附件 Excel` : `${base}；完整数据可在数据问答页面查看或导出 Excel`
+}
+
+/** Results whose rows do not all fit in a message (candidates for a full-data attachment). */
+export function needsAttachment(result, shown) {
+  if (!result || result.error || !result.rows?.length) return false
+  return (result.rowCount ?? result.rows.length) > shown
+}
+
 export function resultMeta(result) {
   return `${result.rowCount ?? result.rows?.length ?? 0} 行${result.truncated ? '（已截断）' : ''}${result.filters?.length ? ` · 已筛选：${result.filters.map(f => f.description).join('；')}` : ''}`
 }
@@ -204,7 +221,7 @@ export function resultAsMarkdownTable(result, maxRows = 10, { maxCols = 8 } = {}
     ...rows.map(r => `| ${cols.map((c, i) => mdCell(c.kind === 'number' && Number.isFinite(Number(r[i])) && r[i] !== null && r[i] !== '' ? Number(r[i]).toLocaleString('en-US', { maximumFractionDigits: 4 }) : r[i])).join(' | ')} |`),
   ]
   const total = result.rowCount ?? result.rows?.length ?? 0
-  if (total > rows.length) lines.push('', `…共 ${total} 行，仅显示前 ${rows.length} 行`)
+  if (total > rows.length) lines.push('', `…共 ${total} 行，仅显示前 ${rows.length} 行${result.attached ? '，完整数据见附件 Excel' : ''}`)
   return lines.join('\n')
 }
 

package/channels/telegram.js

@@ -280,7 +280,7 @@ export function inlineKeyboard(spec) {
 
 // ------------------------------------------------------------ rendering
 
-function resultMarkdown(r, { includeSql, maxRows = 10 } = {}) {
+function resultMarkdown(r, { includeSql, maxRows = 20 } = {}) {
   const head = `**${r.title || '查询结果'}**  ${resultMeta(r)}`
   if (r.error) return `${head}\n${r.error}`
   const lines = [head]
@@ -353,6 +353,16 @@ function createSender(api) {
     return msg?.message_id
   }
 
+  async function sendDocument(chatId, buf, fileName, { caption, threadId } = {}) {
+    const form = new FormData()
+    form.append('chat_id', String(chatId))
+    form.append('document', new Blob([buf], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }), fileName)
+    if (caption) form.append('caption', caption.slice(0, 1024))
+    if (threadId) form.append('message_thread_id', String(threadId))
+    const msg = await api.call('sendDocument', undefined, { form, timeoutMs: 60000 })
+    return msg?.message_id
+  }
+
   /** Deliver an OutboundMessage. Returns { messageId, images }. */
   async function deliver(chatId, message, { replyTo, threadId, renderChartPng = defaultRenderChartPng, logger, buttons = true } = {}) {
     let images = 0
@@ -376,10 +386,16 @@ function createSender(api) {
       messageId ??= id
       reply = undefined
     }
-    return { messageId: messageId === undefined ? undefined : String(messageId), images }
+    // Full data as an Excel document (Bot API sendDocument, ≤ 50 MB).
+    let files = 0
+    let warning
+    if (message.attachment?.buffer) {
+      try { await sendDocument(chatId, message.attachment.buffer, message.attachment.fileName, { caption: '完整数据', threadId }); files++ } catch (error) { warning = `完整数据附件发送失败：${error.message}` }
+    }
+    return { messageId: messageId === undefined ? undefined : String(messageId), images, files, ...(warning ? { warning } : {}) }
   }
 
-  return { sendText, sendPhoto, deliver }
+  return { sendText, sendPhoto, sendDocument, deliver }
 }
 
 // ------------------------------------------------------------ validate
@@ -627,7 +643,7 @@ const telegramBot = {
     { key: 'chatId', type: 'text', required: false, target: true, label: { zh: 'Chat ID（推送目标）', en: 'Chat ID (push target)' }, placeholder: '-1001234567890 / @mychannel', pattern: CHAT_RE.source, help: { zh: '群组/超级群为负数（通常以 -100 开头），公开频道可填 @用户名；仅作机器人使用时可留空', en: 'Negative number for groups (usually -100…), or @username for public channels; may be empty for bot-only use' } },
     { key: 'apiBase', type: 'url', required: false, label: { zh: 'API 地址（可选）', en: 'API base URL (optional)' }, placeholder: DEFAULT_API_BASE, help: { zh: '自建 Bot API 服务器或反向代理地址；留空使用官方 api.telegram.org', en: 'Self-hosted Bot API server or proxy; empty = api.telegram.org' } },
   ],
-  capabilities: { push: true, markdown: 'basic', charts: 'image', chartModes: ['image', 'table'], tables: 'text', buttons: true, bot: true, listTargets: false, mentionAll: false, maxMessageBytes: TEXT_LIMIT },
+  capabilities: { push: true, markdown: 'basic', charts: 'image', chartModes: ['image', 'table'], tables: 'text', tableRows: 20, files: true, buttons: true, bot: true, listTargets: false, mentionAll: false, maxMessageBytes: TEXT_LIMIT },
   setupSteps: {
     zh: [
       '在 Telegram 中打开 @BotFather，发送 /newbot 按提示创建机器人，复制 Bot Token。',

package/channels/wecom.js

@@ -522,7 +522,7 @@ const webhookKind = {
   fields: [
     { key: 'webhookUrl', type: 'secret', secret: true, required: true, label: { zh: 'Webhook 地址', en: 'Webhook URL' }, placeholder: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=…', pattern: WEBHOOK_RE.source, help: { zh: '群聊 → 右上角 … → 消息推送 → 添加，复制 Webhook 地址', en: 'Group chat → … → Message push → Add, copy the webhook URL' } },
   ],
-  capabilities: { push: true, markdown: 'basic', charts: 'image', chartModes: ['image', 'table'], tables: 'markdown', buttons: false, bot: false, listTargets: false, mentionAll: true, maxMessageBytes: WEBHOOK_LIMIT },
+  capabilities: { push: true, markdown: 'basic', charts: 'image', chartModes: ['image', 'table'], tables: 'markdown', tableRows: 10, files: false, buttons: false, bot: false, listTargets: false, mentionAll: true, maxMessageBytes: WEBHOOK_LIMIT },
   setupSteps: {
     zh: [
       '在企业微信群聊中点击右上角「…」→「消息推送」（旧版为「群机器人」）→「添加」，创建后复制 Webhook 地址。',
@@ -553,7 +553,7 @@ const aibotKind = {
     { key: 'chatId', type: 'text', required: false, label: { zh: '推送目标会话 ID（可选）', en: 'Push target chat id (optional)' }, help: { zh: '群聊 chatid（来自机器人收到的消息）或成员 userid；会话需先给机器人发过消息', en: 'Group chatid (from a received message) or member userid; the chat must have messaged the bot first' } },
     { key: 'chatType', type: 'select', required: false, label: { zh: '会话类型', en: 'Chat type' }, options: [{ value: 'group', label: { zh: '群聊', en: 'Group' } }, { value: 'single', label: { zh: '单聊', en: 'Single' } }] },
   ],
-  capabilities: { push: true, markdown: 'full', charts: 'none', chartModes: ['table'], tables: 'markdown', buttons: false, bot: true, listTargets: false, mentionAll: false, maxMessageBytes: AIBOT_LIMIT },
+  capabilities: { push: true, markdown: 'full', charts: 'none', chartModes: ['table'], tables: 'markdown', tableRows: 10, files: false, buttons: false, bot: true, listTargets: false, mentionAll: false, maxMessageBytes: AIBOT_LIMIT },
   setupSteps: {
     zh: [
       '企业微信管理后台 → 应用管理 → 智能机器人 → 创建（或选择）机器人 → 开启「API 模式」并选择「长连接」。',

package/im.js

@@ -1,5 +1,5 @@
 /**
- * Compatibility shim: IM delivery moved to channels/ (see docs/CHANNELS.md).
+ * Compatibility shim: IM delivery moved to channels/ (see docs/channels.md).
  * Platform-neutral helpers live in channels/message.js, Lark cards and push in
  * channels/lark.js. `ImError` is the generic ChannelError.
  */

package/index.js

@@ -310,6 +310,7 @@ function registerSendTool(ctx, service) {
         chartMode: { type: 'string', enum: ['native', 'image', 'table'], description: 'How attached results render: native card charts, PNG images, or tables. Omit to use the channel default; unsupported modes fall back to it.' },
         resultIds: { type: 'array', items: { type: 'string' }, description: 'resultIds from nl2sql_query / nl2sql_chart / nl2sql_overview to include.' },
         includeSql: { type: 'boolean', description: 'Also include each result\'s SQL.' },
+        attachFull: { type: 'boolean', description: 'Where the channel can send files (Lark app bot, Telegram), results with more rows than the message shows get the full data attached as an Excel file. Default true.' },
       },
       additionalProperties: false,
     },
@@ -318,7 +319,7 @@ function registerSendTool(ctx, service) {
     execute: async (args, exec) => {
       try {
         if (args.action === 'list') return { channels: service.listChannels().map(c => ({ ...pick(c, ['id', 'name', 'type', 'platform', 'description', 'isDefault']), ...(c.capabilities ? { capabilities: pick(c.capabilities, ['markdown', 'charts', 'tables', 'chartModes']) } : {}) })) }
-        return await service.sendToChannel({ channelId: args.channel, title: args.title, text: args.text, resultIds: args.resultIds ?? [], includeSql: args.includeSql, chartMode: args.chartMode, source: 'agent', sessionId: exec.agent?.id })
+        return await service.sendToChannel({ channelId: args.channel, title: args.title, text: args.text, resultIds: args.resultIds ?? [], includeSql: args.includeSql, attachFull: args.attachFull, chartMode: args.chartMode, source: 'agent', sessionId: exec.agent?.id })
       } catch (error) {
         throw error instanceof UserError ? new Error(error.message) : error
       }
@@ -495,6 +496,7 @@ function registerRpc(ctx, service) {
     ackSchemaChange: (p) => service.ackSchemaChange(p),
     checkAllSchemas: () => service.checkAllSchemas(),
     listUsers: () => service.listUsers(),
+    listSeenIdentities: (p) => service.listSeenIdentities(p ?? {}),
     saveUser: (p) => service.saveUser(p),
     deleteUser: (p) => service.deleteUser(p.id),
     usageByActor: (p) => service.usageByActor(p?.days ?? 30),

package/lark-bot.js

@@ -1,6 +1,6 @@
 /**
  * Compatibility shim: the Lark long connection and OpenAPI helpers moved to
- * channels/lark.js (see docs/CHANNELS.md).
+ * channels/lark.js (see docs/channels.md).
  */
 export {
   addReaction, clearTenantTokenCache, createDedupe, createLarkBot, getBotInfo, getChatInfo, getTenantToken, getUserInfo,