@hedeqiang/dsh-nl2sql 0.12.2 → 0.13.1

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@hedeqiang/dsh-nl2sql",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "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": {
+    "nl2sql-mcp": "bin/nl2sql-mcp.mjs"
+  },
   "exports": {
     ".": "./index.js",
     "./client": "./lib/client.js",
@@ -10,6 +13,8 @@
     "./icon": "./icon.svg"
   },
   "files": [
+    "bin",
+    "docs/mcp.md",
     "index.js",
     "service/*.js",
     "channels/*.js",
@@ -85,7 +90,7 @@
     "wecom"
   ],
   "engines": {
-    "node": ">=24"
+    "node": ">=18"
   },
   "repository": {
     "type": "git",

package/service/alerts.js

@@ -94,11 +94,13 @@ export const methods = {
     let a = draft ? structuredClone(draft) : { ...found }
     const ds = this.requireDatasource(a.datasourceId)
     let result
+    // Chat-created alerts (service/subscriptions.js) run as their creator, re-resolved now.
+    const actor = a.chatTarget && this.chatAlertActor ? await this.chatAlertActor(a) : undefined
     if (a.source === 'metric') {
       const range = a.grain === 'hour' ? 'last7d' : a.grain === 'month' ? 'thisYear' : a.grain === 'week' ? 'last90d' : 'last30d'
-      result = await this.queryMetric({ datasourceId: ds.id, metric: a.metric, grain: a.grain, range, filters: a.filters, title: `告警 · ${a.name}`, source: 'alert' })
+      result = await this.queryMetric({ datasourceId: ds.id, metric: a.metric, grain: a.grain, range, filters: a.filters, title: `告警 · ${a.name}`, source: 'alert', actor })
     } else {
-      result = await this.runQuery({ sql: a.sql, datasourceId: ds.id, title: `告警 · ${a.name}`, source: 'alert', confirmScan: true })
+      result = await this.runQuery({ sql: a.sql, datasourceId: ds.id, title: `告警 · ${a.name}`, source: 'alert', confirmScan: true, actor })
     }
     // Series: first column = time/category, last numeric column = value.
     const vi = [...result.columns.keys()].reverse().find(i => result.columns[i].kind === 'number')
@@ -120,9 +122,12 @@ export const methods = {
         a.lastFiredAt = Date.now()
         const event = { id: newId('ae'), alertId: a.id, name: a.name, at: Date.now(), value: ev.value ?? null, message: ev.message, resultId: result.resultId }
         this.records.put('alertEvent', event)
-        if (a.channelId) {
+        if (a.channelId || (a.chatTarget && this.deliverAlertToChat)) {
           try {
-            await this.sendToChannel({ channelId: a.channelId, title: `⚠️ 数据告警：${a.name}`, text: `${a.mention ? '<at id=all></at> ' : ''}**${ev.message}**\n\n<font color='grey'>数据源：${ds.name} · 检查时间：${new Date().toLocaleString('zh-CN', { hour12: false })}</font>`, resultIds: [result.resultId], source: 'alert' })
+            // Optional extra Markdown from feature modules (e.g. change attribution, service/proactive.js).
+            const extra = await Promise.resolve(this.beforeAlertPush?.(a, result)).catch(() => null)
+            const msg = { channelId: a.channelId, title: `⚠️ 数据告警：${a.name}`, text: `${a.mention ? '<at id=all></at> ' : ''}**${ev.message}**${extra ? `\n\n${extra}` : ''}\n\n<font color='grey'>数据源：${ds.name} · 检查时间：${new Date().toLocaleString('zh-CN', { hour12: false })}</font>`, resultIds: [result.resultId], source: 'alert' }
+            if (a.chatTarget && this.deliverAlertToChat) await this.deliverAlertToChat(a, msg); else await this.sendToChannel(msg)
             pushed = true
             event.pushed = true
           } catch (error) {
@@ -133,8 +138,9 @@ export const methods = {
       }
     } else if (a.state === 'firing') {
       a.state = 'ok'
-      if (!dryRun && a.channelId && a.notifyRecovery !== false) {
-        try { await this.sendToChannel({ channelId: a.channelId, title: `✅ 告警恢复：${a.name}`, text: ev.message, source: 'alert' }) } catch {}
+      if (!dryRun && (a.channelId || a.chatTarget) && a.notifyRecovery !== false) {
+        const msg = { channelId: a.channelId, title: `✅ 告警恢复：${a.name}`, text: ev.message, source: 'alert' }
+        try { if (a.chatTarget && this.deliverAlertToChat) await this.deliverAlertToChat(a, msg); else await this.sendToChannel(msg) } catch {}
       }
     } else {
       a.state = 'ok'
@@ -221,6 +227,14 @@ export const methods = {
           ran.push({ id: a.id, ok: false, error: error.message })
         }
       }))
+      // Jobs registered by other modules (digest, reconciliation, freshness, quality, goals…):
+      // service.schedulerJobs() returns [{ id, due(now: Date) -> boolean, run() -> Promise }].
+      for (const job of (typeof this.schedulerJobs === 'function' ? this.schedulerJobs(now) : [])) {
+        let isDue = false
+        try { isDue = Boolean(job.due(now)) } catch {}
+        if (!isDue) continue
+        try { await this.withJobLock(`job:${job.id}`, () => job.run()); ran.push({ id: job.id, ok: true }) } catch (error) { if (error.code !== 'nl2sql/busy') ran.push({ id: job.id, ok: false, error: error.message }) }
+      }
       // Daily schema watch (catches up once after downtime).
       const at = this.state.settings.schemaCheckDaily
       if (at) {

package/service/features.js

@@ -0,0 +1,21 @@
+/**
+ * Feature modules. Each entry: { name, methods, rpc?(service), tools?(ctx, service, helpers), start?(ctx, service) }.
+ * - methods: mixed into the service prototype (`this` = service). Methods named `jobs_<name>(now)` return
+ *   scheduler jobs [{ id, due(now), run() }] run by the in-process scheduler (service/alerts.js).
+ * - rpc: page RPC methods; tools: agent tools; start: called after apply (e.g. servers).
+ * New features add a file under service/ and one line here, so they do not edit index.js.
+ */
+import { FEATURE as subscriptions } from './subscriptions.js'
+import { FEATURE as reconcile } from './reconcile.js'
+import { FEATURE as present } from './present.js'
+import { FEATURE as mcp } from './mcp.js'
+import { FEATURE as proactive } from './proactive.js'
+import { FEATURE as freshness } from './freshness.js'
+export const FEATURES = [
+  present,
+  mcp,
+  reconcile,
+  subscriptions,
+  proactive,
+  freshness,
+]

package/service/forecast.js

@@ -0,0 +1,252 @@
+/**
+ * Forecasting (pure functions, no I/O).
+ *
+ * - Holt-Winters additive with weekly seasonality (m = 7) for daily series with ≥ 21 points;
+ * - otherwise Holt's linear trend.
+ * Parameters are fitted by a small grid search minimising the one-step-ahead SSE.
+ * Prediction intervals: residual stddev × 1.96 × sqrt(h).
+ */
+
+const GRID = [0.05, 0.1, 0.2, 0.3, 0.5, 0.7, 0.9]
+const GRID_TREND = [0.01, 0.05, 0.1, 0.2, 0.3]
+const GRID_SEASON = [0.05, 0.1, 0.2, 0.3, 0.5]
+
+/** Holt's linear trend: one-step fitted values, final level/trend. */
+export function holtFit(y, alpha, beta) {
+  const n = y.length
+  if (n < 2) return { fitted: y.map(() => null), level: y[0] ?? 0, trend: 0, sse: 0, count: 0 }
+  let level = y[0]
+  let trend = y[1] - y[0]
+  const fitted = [null]
+  let sse = 0
+  let count = 0
+  for (let t = 1; t < n; t++) {
+    const f = level + trend
+    fitted.push(f)
+    if (t >= 2) { sse += (y[t] - f) ** 2; count++ }
+    const prev = level
+    level = alpha * y[t] + (1 - alpha) * (level + trend)
+    trend = beta * (level - prev) + (1 - beta) * trend
+  }
+  return { fitted, level, trend, sse, count }
+}
+
+/** Holt-Winters additive with season length m (needs ≥ 2 m points). */
+export function holtWintersFit(y, alpha, beta, gamma, m = 7) {
+  const n = y.length
+  const mean = (a) => a.reduce((s, v) => s + v, 0) / a.length
+  const s1 = mean(y.slice(0, m))
+  const s2 = mean(y.slice(m, 2 * m))
+  let level = s1
+  let trend = (s2 - s1) / m
+  // Initial seasonal indices: average deviation from each full season's mean.
+  const seasons = Math.floor(n / m)
+  const season = new Array(m).fill(0)
+  for (let k = 0; k < seasons; k++) {
+    const mk = mean(y.slice(k * m, (k + 1) * m))
+    for (let i = 0; i < m; i++) season[i] += (y[k * m + i] - mk) / seasons
+  }
+  // Level at the end of the first season: start the recursion at t = m.
+  level = s1 + trend * (m - 1) / 2
+  const fitted = new Array(m).fill(null)
+  let sse = 0
+  let count = 0
+  for (let t = m; t < n; t++) {
+    const si = t % m
+    const f = level + trend + season[si]
+    fitted.push(f)
+    sse += (y[t] - f) ** 2
+    count++
+    const prev = level
+    level = alpha * (y[t] - season[si]) + (1 - alpha) * (level + trend)
+    trend = beta * (level - prev) + (1 - beta) * trend
+    season[si] = gamma * (y[t] - level) + (1 - gamma) * season[si]
+  }
+  return { fitted, level, trend, season, sse, count, n, m }
+}
+
+/**
+ * Fit and forecast `horizon` steps ahead.
+ * @param {number[]} values  evenly spaced observations (no nulls)
+ * @param {{ horizon?: number, seasonal?: boolean, period?: number }} opts  seasonal: allow weekly seasonality
+ * @returns {{ method, params, fitted, forecast: { h, value, lower, upper }[], sigma }}
+ */
+export function forecastSeries(values, { horizon = 7, seasonal = true, period = 7 } = {}) {
+  const y = values.map(Number)
+  if (y.length < 3 || y.some(v => !Number.isFinite(v))) throw new Error('至少需要 3 个有效数值才能预测')
+  const H = Math.max(1, Math.min(365, Math.floor(horizon)))
+  const useHW = seasonal && y.length >= 3 * period
+  let best
+  if (useHW) {
+    for (const a of GRID) for (const b of GRID_TREND) for (const g of GRID_SEASON) {
+      const fit = holtWintersFit(y, a, b, g, period)
+      if (!best || fit.sse < best.fit.sse) best = { fit, params: { alpha: a, beta: b, gamma: g } }
+    }
+  } else {
+    for (const a of GRID) for (const b of GRID_TREND) {
+      const fit = holtFit(y, a, b)
+      if (!best || fit.sse < best.fit.sse) best = { fit, params: { alpha: a, beta: b } }
+    }
+  }
+  const { fit, params } = best
+  const sigma = fit.count > 1 ? Math.sqrt(fit.sse / (fit.count - 1)) : 0
+  const forecast = []
+  for (let h = 1; h <= H; h++) {
+    const value = useHW
+      ? fit.level + h * fit.trend + fit.season[(y.length + h - 1) % period]
+      : fit.level + h * fit.trend
+    const w = 1.96 * sigma * Math.sqrt(h)
+    forecast.push({ h, value, lower: value - w, upper: value + w })
+  }
+  return { method: useHW ? 'holt-winters' : 'holt', params, fitted: fit.fitted, forecast, sigma }
+}
+
+// ------------------------------------------------------------ time axis
+
+const DAY = 86400000
+const pad = (n) => String(n).padStart(2, '0')
+const fmtDay = (d) => `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`
+
+/** Parse a time label to { kind, ms } (UTC-based arithmetic, display unchanged). */
+export function parseTimeLabel(v) {
+  const s = String(v ?? '').trim()
+  let m
+  // Dates serialized as midnight ISO timestamps (driver Date → ISO) are days.
+  if ((m = /^(\d{4})-(\d{2})-(\d{2})T00:00:00(?:\.0+)?Z?$/.exec(s))) return { kind: 'day', ms: Date.UTC(+m[1], +m[2] - 1, +m[3]) }
+  if ((m = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})/.exec(s))) return { kind: 'hour', ms: Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5]) }
+  if ((m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s))) return { kind: 'day', ms: Date.UTC(+m[1], +m[2] - 1, +m[3]) }
+  if ((m = /^(\d{4})-(\d{2})$/.exec(s))) return { kind: 'month', ms: Date.UTC(+m[1], +m[2] - 1, 1) }
+  if ((m = /^(\d{4})-W(\d{2})$/.exec(s))) return { kind: 'week', ms: Date.UTC(+m[1], 0, 1) + (+m[2]) * 7 * DAY }
+  if ((m = /^(\d{4})$/.exec(s))) return { kind: 'year', ms: Date.UTC(+m[1], 0, 1) }
+  return null
+}
+
+/**
+ * Turn [{ x, y }] (sorted or not) into an evenly spaced series. Daily series get missing days
+ * filled with 0 (metrics like counts/sums have no row on days without data).
+ * Returns { kind, xs, ys, filled }.
+ */
+export function regularize(points) {
+  const parsed = points.map(p => ({ ...p, t: parseTimeLabel(p.x) })).filter(p => p.y !== null && p.y !== undefined && Number.isFinite(Number(p.y)))
+  const timed = parsed.length >= 2 && parsed.every(p => p.t && p.t.kind === parsed[0].t.kind)
+  if (!timed) return { kind: 'index', xs: parsed.map(p => String(p.x)), ys: parsed.map(p => Number(p.y)), filled: 0 }
+  parsed.sort((a, b) => a.t.ms - b.t.ms)
+  const kind = parsed[0].t.kind
+  if (kind !== 'day') return { kind, xs: parsed.map(p => String(p.x)), ys: parsed.map(p => Number(p.y)), filled: 0 }
+  const byDay = new Map()
+  for (const p of parsed) byDay.set(p.t.ms, (byDay.get(p.t.ms) ?? 0) + Number(p.y))
+  const xs = []
+  const ys = []
+  let filled = 0
+  for (let ms = parsed[0].t.ms; ms <= parsed.at(-1).t.ms; ms += DAY) {
+    xs.push(fmtDay(new Date(ms)))
+    if (byDay.has(ms)) ys.push(byDay.get(ms)); else { ys.push(0); filled++ }
+  }
+  return { kind, xs, ys, filled }
+}
+
+/** Labels for the next `horizon` steps after the last label. */
+export function futureLabels(lastLabel, kind, horizon) {
+  const t = parseTimeLabel(lastLabel)
+  const out = []
+  for (let h = 1; h <= horizon; h++) {
+    if (!t || kind === 'index' || kind === 'week') { out.push(`+${h}`); continue }
+    const d = new Date(t.ms)
+    if (kind === 'day') out.push(fmtDay(new Date(t.ms + h * DAY)))
+    else if (kind === 'hour') { const x = new Date(t.ms + h * 3600000); out.push(`${fmtDay(x)} ${pad(x.getUTCHours())}:00`) }
+    else if (kind === 'month') { const x = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + h, 1)); out.push(`${x.getUTCFullYear()}-${pad(x.getUTCMonth() + 1)}`) }
+    else if (kind === 'year') out.push(String(d.getUTCFullYear() + h))
+  }
+  return out
+}
+
+/** Forecast a labelled series: [{ x, y }] → history + labelled forecast. */
+export function forecastPoints(points, { horizon = 7 } = {}) {
+  const reg = regularize(points)
+  const res = forecastSeries(reg.ys, { horizon, seasonal: reg.kind === 'day' })
+  const labels = futureLabels(reg.xs.at(-1), reg.kind, res.forecast.length)
+  return {
+    method: res.method,
+    params: res.params,
+    sigma: res.sigma,
+    kind: reg.kind,
+    filled: reg.filled,
+    history: reg.xs.map((x, i) => ({ x, y: reg.ys[i] })),
+    forecast: res.forecast.map((f, i) => ({ ...f, x: labels[i] })),
+  }
+}
+
+// ------------------------------------------------------------ digest statistics
+
+/**
+ * Daily comparison for the digest: `values` is a day-indexed array ending with the day
+ * of interest. Compares the last value with the mean / stddev of the 7 days before it
+ * and with the same weekday one week earlier.
+ */
+export function dailyStats(values) {
+  const y = values.map(Number)
+  const cur = y.at(-1)
+  const prev = y.slice(-8, -1)
+  const avg = prev.length ? prev.reduce((s, v) => s + v, 0) / prev.length : null
+  const sd = prev.length > 1 ? Math.sqrt(prev.reduce((s, v) => s + (v - avg) ** 2, 0) / (prev.length - 1)) : null
+  const lastWeek = y.length >= 8 ? y.at(-8) : null
+  const pct = (a, b) => (b === null || b === undefined || b === 0 ? null : (a - b) / Math.abs(b))
+  return {
+    value: cur,
+    avg7: avg,
+    sd7: sd,
+    z: sd ? (cur - avg) / sd : null,
+    vsAvg: pct(cur, avg),
+    lastWeek,
+    vsLastWeek: pct(cur, lastWeek),
+  }
+}
+
+/** Is a daily comparison notable? |z| > zLimit or |Δ% vs 7-day avg| > pctLimit. */
+export function isNotable(stats, { z = 2, pct = 0.3 } = {}) {
+  return (stats.z !== null && Math.abs(stats.z) > z) || (stats.vsAvg !== null && Math.abs(stats.vsAvg) > pct)
+}
+
+// ------------------------------------------------------------ goals
+
+/**
+ * Period bounds (local calendar) containing `now`: { start, end } as Date (end exclusive).
+ */
+export function periodBounds(period, now = new Date()) {
+  const y = now.getFullYear()
+  const m = now.getMonth()
+  if (period === 'year') return { start: new Date(y, 0, 1), end: new Date(y + 1, 0, 1) }
+  if (period === 'quarter') { const q = Math.floor(m / 3) * 3; return { start: new Date(y, q, 1), end: new Date(y, q + 3, 1) } }
+  return { start: new Date(y, m, 1), end: new Date(y, m + 1, 1) }
+}
+
+/**
+ * Run-rate projection. `daily`: [{ date: Date (local midnight), value }] for complete days
+ * from the period start up to yesterday. Remaining days (today .. end-1) are projected with
+ * the per-weekday mean when every weekday has a sample, else the overall daily mean.
+ * Returns { projected, weekdayAware, remainingDays } (projected null without data).
+ */
+export function projectRunRate({ daily, actualComplete, today, end }) {
+  const remaining = []
+  for (let d = new Date(today); d < end; d.setDate(d.getDate() + 1)) remaining.push(new Date(d))
+  if (!daily.length) return { projected: null, weekdayAware: false, remainingDays: remaining.length }
+  const all = daily.reduce((s, d) => s + d.value, 0) / daily.length
+  const byWd = new Map()
+  for (const d of daily) { const w = d.date.getDay(); const e = byWd.get(w) ?? { s: 0, n: 0 }; e.s += d.value; e.n++; byWd.set(w, e) }
+  const weekdayAware = byWd.size === 7
+  let rest = 0
+  for (const d of remaining) rest += weekdayAware ? byWd.get(d.getDay()).s / byWd.get(d.getDay()).n : all
+  return { projected: actualComplete + rest, weekdayAware, remainingDays: remaining.length }
+}
+
+/** Goal status from actual-to-date and projection. */
+export function goalStatus({ direction = 'up', target, actual, projected, ended = false }) {
+  if (direction === 'down') {
+    if (actual > target) return 'missed'
+    if (ended) return 'achieved'
+    return projected === null || projected <= target ? 'on-track' : 'at-risk'
+  }
+  if (actual >= target) return 'achieved'
+  if (ended) return 'missed'
+  return projected !== null && projected >= target ? 'on-track' : 'at-risk'
+}