@hedeqiang/dsh-nl2sql 0.10.0 → 0.11.1

package/service/lark-actions.js

@@ -1,223 +0,0 @@
-/**
- * Nl2SqlService methods: interactive buttons on Lark bot answer cards.
- * Mixed into the service prototype by index.js; `this` is the service.
- *
- * Buttons carry only an opaque token ({ a: <action>, t: <token> }); the token
- * maps server-side to { resultId, sessionId, chatId, replyTo, depth, ownerRole }.
- * Every click re-resolves the clicking operator and re-checks data source
- * scope, row-level rules and role before anything runs.
- */
-import { randomBytes } from 'node:crypto'
-import { parseSelect } from '../analysis.js'
-import { buildCard } from '../im.js'
-import { getUserInfo, replyMessage, replyText } from '../lark-bot.js'
-import { toUserError } from './shared.js'
-
-export const ACTION_TOKEN_TTL_MS = 7 * 24 * 3600 * 1000
-const ACTION_TOKEN_MAX = 5000
-export const ACTION_RATE_MS = 2000
-/** Cards produced by button actions get buttons up to this depth (0 = answer card). */
-export const ACTION_MAX_DEPTH = 2
-const ACTIONS = new Set(['drill', 'why', 'detail', 'pin'])
-const ACTION_LABEL = { drill: '拆分', why: '为什么变化', detail: '明细', pin: '固定到看板' }
-
-const toast = (type, content) => ({ toast: { type, content } })
-
-function hasAggregate(r, dialect) {
-  const parsed = parseSelect(r.baseSql ?? r.sql, { dialect })
-  return Boolean(parsed?.select?.some(i => i.isAggregate))
-}
-
-export const methods = {
-  // ------------------------------------------------------------- tokens
-
-  /** Store context for a card's buttons; returns the opaque token. */
-  createLarkActionToken(ctx) {
-    const token = randomBytes(9).toString('base64url')
-    const now = Date.now()
-    const body = { resultId: ctx.resultId, sessionId: ctx.sessionId ?? null, chatId: ctx.chatId ?? null, chatType: ctx.chatType === 'p2p' ? 'p2p' : 'group', replyTo: ctx.replyTo ?? null, depth: ctx.depth ?? 0, ownerRole: ctx.ownerRole ?? null }
-    this.larkActionTokens ??= new Map()
-    this.larkActionTokens.set(token, { ...body, created: now })
-    while (this.larkActionTokens.size > ACTION_TOKEN_MAX) this.larkActionTokens.delete(this.larkActionTokens.keys().next().value)
-    try {
-      this.store?.putActionToken(token, body, now)
-      if ((this.larkTokenWrites = (this.larkTokenWrites ?? 0) + 1) % 200 === 0) this.store?.pruneActionTokens(ACTION_TOKEN_TTL_MS, ACTION_TOKEN_MAX)
-    } catch {}
-    return token
-  },
-
-  /** Context for a token, or undefined when unknown / expired. */
-  lookupLarkActionToken(token, now = Date.now()) {
-    if (typeof token !== 'string' || !/^[\w-]{8,32}$/.test(token)) return undefined
-    let ctx = this.larkActionTokens?.get(token)
-    if (!ctx) { try { ctx = this.store?.getActionToken(token) } catch {} }
-    if (!ctx || now - ctx.created > ACTION_TOKEN_TTL_MS) return undefined
-    return ctx
-  },
-
-  // ------------------------------------------------------------- building
-
-  /**
-   * Button spec (see im.js actionElement) for one result shown to `actor` in a
-   * chat, or undefined when nothing applies. Never throws.
-   */
-  async larkCardActions(result, { actor, sessionId, chatId, chatType, replyTo, depth = 0 } = {}) {
-    try {
-      if (!result?.resultId || result.error || depth >= ACTION_MAX_DEPTH) return undefined
-      const ds = this.findDatasource(result.datasourceId)
-      if (!ds) return undefined
-      const dialect = ds.type ?? 'mysql'
-      const role = actor?.role ?? 'analyst'
-      const token = this.createLarkActionToken({ resultId: result.resultId, sessionId, chatId, chatType, replyTo, depth, ownerRole: role })
-      const aggregate = hasAggregate(result, dialect)
-      const buttons = []
-      let select
-      if (aggregate) {
-        let dims = []
-        try { dims = (await this.drillDimensions(result.resultId)).dimensions } catch {}
-        const xName = result.chart?.x
-        dims = dims.filter(d => d.column !== xName && d.column.split('.').pop() !== xName).slice(0, 6)
-        if (dims.length) select = { placeholder: '按维度拆分', value: { a: 'drill', t: token }, options: dims.map(d => ({ text: d.label && d.label !== d.column ? `${d.label}（${d.column}）` : d.column, value: d.column })) }
-      }
-      const xi = result.chart?.x ? result.columns.findIndex(c => c.name === result.chart.x) : -1
-      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 (!select && !buttons.length) return undefined
-      return { ...(select ? { select } : {}), buttons }
-    } catch (error) {
-      console.warn('nl2sql lark: cannot build card actions: %s', error.message)
-      return undefined
-    }
-  },
-
-  /** Results with their button specs attached (for buildCard). */
-  async withLarkCardActions(results, ctx) {
-    const out = []
-    for (const r of results) {
-      const cardActions = await this.larkCardActions(r, ctx)
-      out.push(cardActions ? { ...r, cardActions } : r)
-    }
-    return out
-  },
-
-  /** Reply with a card, falling back to no charts, then no buttons, then text. */
-  async replyLarkCard(creds, messageId, message) {
-    const attempts = [{}, { charts: false }, { charts: false, actions: false }]
-    let lastError
-    for (const opts of attempts) {
-      try { return await replyMessage({ ...creds, messageId, card: buildCard(message, opts) }) } catch (error) { lastError = error }
-    }
-    try { return await replyText({ ...creds, messageId, text: String(message.text ?? '').slice(0, 3000) || `回复失败：${lastError?.message}` }) } catch {}
-    return undefined
-  },
-
-  // ------------------------------------------------------------- clicks
-
-  /**
-   * card.action.trigger (normalized by lark-bot.js). Authorizes synchronously
-   * and returns a toast within Feishu's 3 s window; the analysis runs in the
-   * background and replies in the chat with a new card.
-   */
-  async handleLarkCardAction(evt) {
-    const creds = this.larkCreds
-    if (!creds || !evt?.operator?.openId) return undefined
-    const a = evt.value?.a
-    const ctx = this.lookupLarkActionToken(evt.value?.t)
-    const deny = (msg, detail) => { this.auditAdmin('larkbot.action.denied', `${evt.operator.openId} · ${a ?? '?'} · ${detail ?? msg}`); return toast('error', msg) }
-    // Per-operator rate limit.
-    this.larkActionRate ??= new Map()
-    const now = Date.now()
-    const last = this.larkActionRate.get(evt.operator.openId) ?? 0
-    if (now - last < ACTION_RATE_MS) return toast('warning', '操作太频繁，请稍后再试。')
-    this.larkActionRate.set(evt.operator.openId, now)
-    if (this.larkActionRate.size > 2000) for (const [k, t] of this.larkActionRate) if (now - t > ACTION_RATE_MS) this.larkActionRate.delete(k)
-
-    if (!ACTIONS.has(a) || !ctx) return deny('该按钮已过期或无效，请重新提问。', 'unknown/expired token')
-    if (ctx.chatId && evt.chatId && ctx.chatId !== evt.chatId) return deny('该按钮不属于当前聊天。', 'chat mismatch')
-    // Who clicked: resolved from our member list, never from the callback value.
-    let user = {}
-    let timer
-    try { user = await Promise.race([getUserInfo({ ...creds, openId: evt.operator.openId }), new Promise(r => { timer = setTimeout(() => r({}), 1200) })]) } catch {} finally { clearTimeout(timer) }
-    const chatId = ctx.chatId ?? evt.chatId
-    const resolved = this.resolveLarkActor({ openId: evt.operator.openId, email: user.email, name: user.name ?? evt.operator.name, chatId, chatType: ctx.chatType ?? 'group' })
-    if (resolved.refused) return deny(resolved.refused, 'actor refused')
-    const actor = { ...resolved.actor, kind: 'lark' }
-    const r = this.lookupResult(ctx.resultId)
-    if (!r) return deny('结果已过期，请重新提问。', 'result expired')
-    try { this.assertResultAccess(r, actor) } catch (error) { return deny(toUserError(error).message, `${actor.name}: ${error.message}`) }
-    if (actor.role === 'viewer') {
-      // Viewers may only act on governed results (produced under viewer rules, or a verified example / dashboard SQL).
-      const ds = this.findDatasource(r.datasourceId)
-      const governed = ctx.ownerRole === 'viewer' || (ds && this.isVerifiedExample(ds, r.baseSql ?? r.sql))
-      if (!governed || a === 'detail' || a === 'pin') return deny(a === 'pin' ? '只读成员不能固定到看板。' : a === 'detail' ? '只读成员不能查看明细数据。' : '只读成员只能分析指标库或已验证问答的结果。', `${actor.name}: viewer`)
-    }
-    if (a === 'pin' && actor.role !== 'admin' && actor.role !== 'analyst') return deny('只有管理员或分析师可以固定到看板。', `${actor.name}: role ${actor.role}`)
-    let dimension
-    if (a === 'drill') {
-      dimension = typeof evt.option === 'string' ? evt.option : undefined
-      let allowed = []
-      try { allowed = (await this.drillDimensions(r.resultId)).dimensions.map(d => d.column) } catch {}
-      if (!dimension || !allowed.includes(dimension)) return deny('请选择一个有效的拆分维度。', `invalid dimension ${String(dimension).slice(0, 40)}`)
-    }
-
-    if (a === 'pin') {
-      try {
-        const widget = await this.pinWidget({ title: r.title || '飞书结果', sql: r.baseSql ?? r.sql, datasourceId: r.datasourceId, chart: r.chart })
-        const board = this.currentDashboardObj()
-        this.auditAdmin('larkbot.pin', `${actor.name} · ${widget.title} → ${board.name}`, actor)
-        this.recordDelivery({ channel: { id: 'larkbot', name: `飞书机器人 · ${actor.name}` }, title: `固定：${widget.title}`.slice(0, 60), status: 'ok', results: 0, source: 'larkbot', sessionId: ctx.sessionId, elapsedMs: Date.now() - now })
-        await this.save()
-        return toast('success', `已固定到看板「${board.name}」`)
-      } catch (error) {
-        return toast('error', `固定失败：${toUserError(error).message}`.slice(0, 200))
-      }
-    }
-
-    const job = this.runLarkCardAction({ a, ctx, r, actor, dimension, evt, creds })
-    this.larkActionJobs ??= new Set()
-    this.larkActionJobs.add(job)
-    job.finally(() => this.larkActionJobs.delete(job)).catch(() => {})
-    return toast('info', '正在分析…')
-  },
-
-  async runLarkCardAction({ a, ctx, r, actor, dimension, evt, creds }) {
-    const started = Date.now()
-    const replyTo = ctx.replyTo ?? evt.messageId
-    const label = a === 'drill' ? `拆分：${dimension}` : a === 'why' ? '为什么变化' : `明细：${r.chart?.x ?? ''}`
-    const footer = `数据问答 · ${r.datasourceName ?? ''} · ${actor.name}`
-    let status = 'ok'
-    let error
-    let resultsCount = 0
-    try {
-      let message
-      if (a === 'drill' || a === 'detail') {
-        let xValue
-        if (a === 'detail') {
-          const xi = r.columns.findIndex(c => c.name === r.chart?.x)
-          xValue = r.rows.map(row => row[xi]).filter(v => v !== null && v !== undefined).at(-1)
-        }
-        const out = await this.drill({ resultId: r.resultId, mode: a === 'drill' ? 'breakdown' : 'detail', dimension, xValue, sessionId: ctx.sessionId ?? undefined, actor, source: 'larkbot' })
-        const results = await this.withLarkCardActions([out], { actor, sessionId: ctx.sessionId, chatId: ctx.chatId ?? evt.chatId, chatType: ctx.chatType, replyTo, depth: (ctx.depth ?? 0) + 1 })
-        resultsCount = 1
-        message = { title: out.title || label, text: a === 'detail' ? `「${r.title || '结果'}」在 ${r.chart?.x}=${xValue} 的明细（最多 200 行）。` : `「${r.title || '结果'}」按 ${dimension} 拆分。`, results, footer }
-      } else {
-        const out = await this.explainChange({ resultId: r.resultId, sessionId: ctx.sessionId ?? undefined, actor })
-        const top = out.dimensions.find(d => d.attribution)
-        const rows = (top?.attribution.items ?? []).slice(0, 8)
-        const table = rows.length ? `\n\n| ${top.dimension} | ${out.baseline} | ${out.current} | 变化 |\n|---|---|---|---|\n${rows.map(i => `| ${i.value ?? 'NULL'} | ${i.baseline} | ${i.current} | ${i.delta >= 0 ? '+' : ''}${i.delta} |`).join('\n')}` : ''
-        message = { title: `为什么变化 · ${r.title || ''}`.slice(0, 80), text: `${out.summary}${table}`, results: [], footer }
-      }
-      await this.replyLarkCard(creds, replyTo, message)
-    } catch (e) {
-      status = 'error'
-      error = toUserError(e).message
-      try { await replyText({ ...creds, messageId: replyTo, text: `${label} 失败：${error}`.slice(0, 1000) }) } catch {}
-    }
-    this.auditAdmin('larkbot.action', `${actor.name} · ${label} · ${r.resultId}${error ? ` · ${error}` : ''}`, actor)
-    this.recordDelivery({ channel: { id: 'larkbot', name: `飞书机器人 · ${actor.name}` }, title: label.slice(0, 60), status, ...(error ? { error } : {}), results: resultsCount, source: 'larkbot', sessionId: ctx.sessionId, elapsedMs: Date.now() - started })
-    await this.save()
-  },
-}

package/service/lark.js

@@ -1,250 +0,0 @@
-/**
- * Nl2SqlService methods: lark.
- * Mixed into the service prototype by index.js; `this` is the service.
- */
-import { addReaction, createLarkBot, getChatInfo, getUserInfo, replyText } from '../lark-bot.js'
-import { PRESET_ID, UserError, hashText, oneOf, toUserError } from './shared.js'
-
-export const methods = {
-  // ------------------------------------------------------------- Lark bot
-
-  /**
-   * Inbound Lark bot: people @ the app bot in a group (or DM it); each chat
-   * gets its own nl2sql session bound to a data source the sender may use.
-   * Config: { enabled, channelId (lark_app channel providing credentials),
-   * replyMode: 'card', sessionPerChat: true, allowP2p: true }.
-   */
-  larkBotConfig() {
-    return { enabled: false, channelId: null, allowP2p: true, sessionScope: 'chat', ...(this.state.larkBot ?? {}) }
-  },
-
-  larkBotStatus() {
-    const conf = this.larkBotConfig()
-    const status = this.larkBot?.status() ?? { state: conf.enabled ? 'stopped' : 'idle', since: Date.now() }
-    return { ...conf, status, bot: this.larkBot?.botInfo?.() ?? null, conversations: Object.values(this.state.larkSessions ?? {}).sort((a, b) => b.lastAt - a.lastAt).slice(0, 50) }
-  },
-
-  async saveLarkBot(input) {
-    const conf = this.larkBotConfig()
-    if (input.channelId !== undefined) {
-      const ch = this.state.channels.find(c => c.id === input.channelId)
-      if (input.channelId && (!ch || ch.type !== 'lark_app')) throw new UserError('nl2sql/invalid', '飞书机器人需要选择一个「应用机器人」类型的推送渠道（提供 App ID / Secret）')
-      conf.channelId = input.channelId || null
-    }
-    if (input.enabled !== undefined) conf.enabled = Boolean(input.enabled)
-    if (input.allowP2p !== undefined) conf.allowP2p = Boolean(input.allowP2p)
-    if (input.sessionScope !== undefined) conf.sessionScope = oneOf(input.sessionScope, ['chat', 'user'], 'sessionScope')
-    if (conf.enabled && !conf.channelId) throw new UserError('nl2sql/invalid', '请先选择应用机器人渠道')
-    this.state.larkBot = conf
-    this.auditAdmin('larkbot.save', `${conf.enabled ? '启用' : '停用'} · ${conf.channelId ?? ''}`)
-    await this.save()
-    await this.restartLarkBot()
-    return this.larkBotStatus()
-  },
-
-  async restartLarkBot() {
-    if (this.larkBot) { try { await this.larkBot.stop() } catch {} this.larkBot = undefined }
-    const conf = this.larkBotConfig()
-    if (!conf.enabled || this.disposed) return
-    const ch = this.state.channels.find(c => c.id === conf.channelId)
-    if (!ch) return
-    const secrets = await this.channelSecrets(ch)
-    this.larkCreds = { appId: ch.appId, appSecret: secrets.appSecret, domain: ch.domain === 'lark' ? 'lark' : 'feishu' }
-    this.larkBot = createLarkBot({
-      ...this.larkCreds,
-      logger: { debug() {}, info() {}, warn: (...a) => console.warn('nl2sql lark:', ...a), error: (...a) => console.warn('nl2sql lark:', ...a) },
-      onStatus: () => {},
-      onMessage: (m) => { this.handleLarkMessage(m).catch(error => console.warn('nl2sql lark: handler failed: %s', error.message)) },
-      onCardAction: (evt) => this.handleLarkCardAction(evt),
-    })
-    await this.larkBot.start()
-  },
-
-  /** One inbound message → permission check → session prompt → reply card. */
-  async handleLarkMessage(m) {
-    const conf = this.larkBotConfig()
-    const creds = this.larkCreds
-    if (!creds) return
-    if (m.chatType === 'group' && !m.mentionedBot) return
-    if (m.chatType === 'p2p' && !conf.allowP2p) return
-    const text = (m.text ?? '').trim()
-    if (!text) return
-    const reply = (t) => replyText({ ...creds, messageId: m.messageId, text: t }).catch(() => {})
-    try {
-      await this.handleLarkMessageInner(m, text, conf, creds, reply)
-    } catch (error) {
-      console.warn('nl2sql lark: %s', error.message)
-      await reply(`处理失败：${toUserError(error).message}`)
-    }
-  },
-
-  async handleLarkMessageInner(m, text, conf, creds, reply) {
-    let user = {}
-    try { user = await getUserInfo({ ...creds, openId: m.sender.openId }) } catch {}
-    const resolved = this.resolveLarkActor({ openId: m.sender.openId, email: user.email, name: user.name, chatId: m.chatId, chatType: m.chatType })
-    if (resolved.refused) { await reply(resolved.refused); return }
-    const actor = resolved.actor
-    // Commands: 帮助 / 数据源 / 切换 <名称> / 新对话
-    const cmd = text.match(/^\/?(帮助|help|数据源|切换数据源|切换|新对话|reset)\s*(.*)$/i)
-    // Members with different scopes must not share a conversation: per-user sessions
-    // whenever the sender's effective scope or rules differ from the chat's.
-    const scopeSig = JSON.stringify([actor.datasourceIds, actor.role, actor.rowRules ?? []])
-    const shared = conf.sessionScope !== 'user'
-    let key = shared ? `${m.chatId}#${hashText(scopeSig)}` : `${m.chatId}:${m.sender.openId}`
-    this.state.larkSessions ??= {}
-    const conv = this.state.larkSessions[key] ?? { key, chatId: m.chatId, chatType: m.chatType, sessionId: null, datasourceId: actor.defaultDatasourceId, createdAt: Date.now() }
-    const allowedDs = this.state.datasources.filter(d => !Array.isArray(actor.datasourceIds) || actor.datasourceIds.includes(d.id))
-    if (conv.datasourceId && !allowedDs.some(d => d.id === conv.datasourceId)) conv.datasourceId = allowedDs[0]?.id ?? null
-    if (cmd) {
-      const verb = cmd[1].toLowerCase()
-      if (verb === '帮助' || verb === 'help') { await reply(`直接 @我 提问即可，例如「上周每天的订单量」。\n命令：数据源（查看可用数据源）、切换 <名称>、新对话。\n当前数据源：${this.findDatasource(conv.datasourceId)?.name ?? '未选择'}${actor.role === 'viewer' ? '\n你是只读成员：可以查询指标库中的指标、已验证的常见问题和看板。' : ''}`); return }
-      if (verb === '数据源') { await reply(`可用数据源：${allowedDs.map(d => d.name).join('、') || '无'}\n当前：${this.findDatasource(conv.datasourceId)?.name ?? '未选择'}`); return }
-      if (verb === '新对话' || verb === 'reset') { conv.sessionId = null; this.state.larkSessions[key] = conv; await this.save(); await reply('已开始新对话。'); return }
-      const target = allowedDs.find(d => d.name === cmd[2].trim() || d.id === cmd[2].trim())
-      if (!target) { await reply(`找不到可用的数据源「${cmd[2]}」。可用：${allowedDs.map(d => d.name).join('、')}`); return }
-      conv.datasourceId = target.id
-      if (conv.sessionId) { this.state.sessions[conv.sessionId] = target.id }
-      this.state.larkSessions[key] = conv
-      await this.save()
-      await reply(`已切换到数据源「${target.name}」。`)
-      return
-    }
-    const ds = this.findDatasource(conv.datasourceId) ?? allowedDs[0]
-    if (!ds) { await reply('没有可访问的数据源，请联系管理员。'); return }
-    this.assertAccess(actor, ds)
-    if (!this.ctx.get('sessionController')) { await reply('当前 Harness 不支持创建会话（缺少 sessionController）。'); return }
-    void addReaction({ ...creds, messageId: m.messageId, emojiType: 'OnIt' })
-    if (!conv.chatName && m.chatType === 'group') { try { conv.chatName = (await getChatInfo({ ...creds, chatId: m.chatId })).name } catch {} }
-    // One prompt at a time per conversation, so each question gets its own answer.
-    await this.serialize(`lark:${key}`, async () => {
-      const started = Date.now()
-      // Another message of this conversation may have created the session meanwhile.
-      const latest = this.state.larkSessions[key]
-      if (latest?.sessionId && !conv.sessionId) conv.sessionId = latest.sessionId
-      const prepare = async (sessionId) => {
-        conv.sessionId = sessionId
-        conv.datasourceId = ds.id
-        conv.lastAt = started
-        conv.lastQuestion = text.slice(0, 200)
-        conv.lastActor = actor.name
-        this.state.larkSessions[key] = conv
-        this.state.sessions[sessionId] = ds.id
-        this.state.sessionActors ??= {}
-        this.state.sessionActors[sessionId] = { id: actor.id, name: actor.name, kind: 'lark', datasourceIds: actor.datasourceIds, role: actor.role, rowRules: actor.rowRules ?? [] }
-        await this.save()
-      }
-      const prompt = `[飞书${m.chatType === 'group' ? `群「${conv.chatName ?? m.chatId}」` : '私聊'} · ${actor.name}${actor.role === 'viewer' ? ' · 只读成员' : ''}] ${text}\n\n（回答会以飞书卡片发回该聊天：请用简洁的中文 Markdown 写结论，必要时附上查询结果；不要调用 nl2sql_send，也不要向用户提问——有歧义时说明你的假设后直接回答。${actor.role === 'viewer' ? '该成员是只读角色：只能用 nl2sql_metric 查询指标库，或复用 nl2sql_knowledge 中已验证的样例 SQL；不能自由编写 SQL。' : ''}）`
-      const turn = await this.runAgentTurn({ sessionId: conv.sessionId, title: `飞书 · ${conv.chatName ?? actor.name}`, requestId: `lark-${m.messageId}`, text: prompt, prepare, timeoutMs: 600000 })
-      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: 'lark' }); return true } catch { return false } }).slice(-4)
-      // Buttons (拆分 / 为什么变化 / 明细 / 固定到看板) carry opaque tokens only; see service/lark-actions.js.
-      const withActions = await this.withLarkCardActions(results, { actor, sessionId: conv.sessionId, chatId: m.chatId, chatType: m.chatType, replyTo: m.messageId, depth: 0 })
-      await this.replyLarkCard(creds, m.messageId, { title: text.length > 40 ? `${text.slice(0, 40)}…` : text, text: body || '（没有生成文字回答）', results: withActions, footer: `数据问答 · ${ds.name} · ${actor.name}` })
-      void addReaction({ ...creds, messageId: m.messageId, emojiType: turn.reason === 'idle' ? 'DONE' : 'CrossMark' })
-      this.recordDelivery({ channel: { id: 'larkbot', name: `飞书机器人 · ${conv.chatName ?? actor.name}` }, title: text.slice(0, 60), status: turn.reason === 'idle' ? 'ok' : 'error', ...(turn.reason === 'idle' ? {} : { error: turn.reason }), results: results.length, source: 'larkbot', sessionId: conv.sessionId, elapsedMs: Date.now() - started })
-      await this.save()
-    })
-  },
-
-  /** Run tasks with the same key one after another. */
-  serialize(key, task) {
-    this.queues ??= new Map()
-    const prev = this.queues.get(key) ?? Promise.resolve()
-    const next = prev.catch(() => {}).then(task)
-    this.queues.set(key, next)
-    next.finally(() => { if (this.queues.get(key) === next) this.queues.delete(key) }).catch(() => {})
-    return next
-  },
-
-  /**
-   * Prompt an nl2sql session and collect exactly the answer of that prompt's
-   * turn. Creates (or recreates, if archived / missing) the session, handles
-   * timeouts and pending questions by cancelling the turn.
-   * @returns {{ sessionId, text, resultIds, reason: 'idle'|'timeout'|'input-required' }}
-   */
-  async runAgentTurn({ sessionId, title, requestId, text, prepare, timeoutMs = 300000 }) {
-    const controller = this.ctx.get('sessionController')
-    const registry = this.ctx.get('workspaceRegistry')
-    const create = async () => {
-      const created = await controller.create({ agentPreset: PRESET_ID, ...(this.state.settings.botCwd ? { cwd: this.state.settings.botCwd } : {}) })
-      try { await controller.rename?.({ sessionId: created.sessionId, title }) } catch {}
-      return created.sessionId
-    }
-    let sid = sessionId
-    if (sid && (registry?.archivedSessionIds?.includes?.(sid))) sid = null
-    if (!sid) sid = await create()
-    await prepare?.(sid)
-    const send = (id) => controller.prompt({ requestId, sessionId: id, mode: 'queue', content: [{ type: 'text', text }] }, new AbortController().signal)
-    try {
-      await send(sid)
-    } catch (error) {
-      const code = error?.code ?? ''
-      if (!/not-found|archived|writer-held/.test(code) && !/not found|archived/i.test(error?.message ?? '')) throw error
-      sid = await create()
-      await prepare?.(sid)
-      await send(sid)
-    }
-    const waited = await controller.wait({ sessionId: sid, timeoutMs, maxMessages: 1 }, new AbortController().signal)
-    const reason = waited?.reason ?? 'idle'
-    if (reason !== 'idle') { try { controller.cancel({ sessionId: sid }) } catch {} }
-    const answer = await this.collectTurnByRequest(sid, requestId)
-    return { sessionId: sid, reason, ...answer }
-  },
-
-  /** Session events (live or persisted). */
-  async sessionEvents(sessionId) {
-    const live = this.ctx.get('agents')?.get(sessionId)?.session
-    const read = (session) => session.snapshotEvents()
-    if (live) return read(live)
-    const q = this.ctx.get('sessionQuery')
-    return q ? q.inspectSession(sessionId, read) : []
-  },
-
-  /**
-   * Answer of the turn started by the user message carrying `requestId`:
-   * the last assistant text of that turn and the nl2sql resultIds it produced.
-   */
-  async collectTurnByRequest(sessionId, requestId) {
-    const events = await this.sessionEvents(sessionId)
-    const at = events.findIndex(e => e.type === 'user/message' && (e.data?.source?.rpcId === requestId || e.data?.source?.requestId === requestId))
-    if (at < 0) return { text: '', resultIds: [] }
-    let turn
-    for (let i = at + 1; i < events.length; i++) {
-      const e = events[i]
-      if (e.type === 'turn/start') { turn = e.data.turn; break }
-      if (e.data?.turn !== undefined) { turn = e.data.turn; break }
-    }
-    if (turn === undefined) return { text: '', resultIds: [] }
-    let text = ''
-    const resultIds = []
-    for (const e of events.slice(at + 1)) {
-      if (e.data?.turn !== undefined && e.data.turn !== turn) { if (e.data.turn > turn) break; continue }
-      if (e.type === 'assistant/message') {
-        const t = (e.data.message?.content ?? []).filter(b => b.type === 'text').map(b => b.text).join('\n\n').trim()
-        if (t) text = t
-      }
-      if (e.type === 'tool/result') {
-        const meta = e.data.meta
-        if (meta?.resultId) resultIds.push(meta.resultId)
-        for (const r of meta?.results ?? []) if (r.resultId) resultIds.push(r.resultId)
-      }
-      if (e.type === 'turn/end' && e.data.turn === turn) break
-    }
-    return { text, resultIds: [...new Set(resultIds)] }
-  },
-
-  /** Back-compat for callers that only have the live session and a seq anchor. */
-  collectTurnAnswer(sessionId, afterSeq) {
-    const session = this.ctx.get('agents')?.get(sessionId)?.session
-    if (!session) return { text: '', resultIds: [] }
-    let text = ''
-    const resultIds = []
-    for (const e of session.snapshotEvents().filter(x => x.seq > afterSeq)) {
-      if (e.type === 'assistant/message') { const t = (e.data.message?.content ?? []).filter(b => b.type === 'text').map(b => b.text).join('\n\n').trim(); if (t) text = t }
-      if (e.type === 'tool/result') { const meta = e.data.meta; if (meta?.resultId) resultIds.push(meta.resultId); for (const r of meta?.results ?? []) if (r.resultId) resultIds.push(r.resultId) }
-    }
-    return { text, resultIds: [...new Set(resultIds)] }
-  },
-}