dsh-plugin-show-me-data 0.1.0

package/lib/app/ai.js

@@ -0,0 +1,440 @@
+/**
+ * The AI orchestration layer (docs/06 §1–§6).
+ *
+ * One place assembles the digest, calls the gateway, validates the answer,
+ * retries once with feedback, degrades to the deterministic gateway, and caches
+ * the result. Nothing here trusts the model: a violation never reaches the user.
+ *
+ * @module app/ai
+ */
+import { buildDigest } from '../core/insight/digest.js'
+import { buildProposePrompt, buildExplainPrompt, buildSummaryPrompt, buildAnswerPrompt, buildOverviewPrompt } from '../core/ai/prompts.js'
+import { fingerprint } from '../core/insight/rank.js'
+import { decideAction, buildValidationData, validateAnswer, violationLines } from './ai-validate.js'
+import { searchIndicators } from '../core/indicators/resolve.js'
+import { inRange } from '../core/time/range.js'
+
+/** Default AI cache TTL in minutes (docs/06 §6). */
+export const AI_CACHE_MINUTES = 60
+
+/** Human labels for the analysis scopes the panel can request. */
+export const SCOPE_LABELS = {
+  ALL: '全部指标',
+  US: '美国',
+  CN: '中国',
+  GLOBAL: '全球',
+  CUSTOM: '自选',
+}
+
+/**
+ * Create the AI use cases.
+ *
+ * @param {object} deps - dependencies.
+ * @param {object} deps.gateway - primary 'AiGateway'.
+ * @param {object} deps.fallback - deterministic 'AiGateway'.
+ * @param {object} deps.overview - the overview use case (source of digest entries).
+ * @param {Record<string, object>} deps.catalogById - catalog index.
+ * @param {import('../ports/snapshot-repo.js').SnapshotRepository} deps.snapshots - cache.
+ * @param {import('../ports/clock.js').Clock} deps.clock - clock.
+ * @param {object} [deps.propose] - propose use case.
+ * @param {(msg: string, meta?: object) => void} [deps.log] - logger.
+ * @param {{ maxAttempts?: number, cacheMinutes?: number, digestBudget?: number }} [deps.options] - tuning.
+ * @returns {object} AI use cases.
+ */
+export function createAiUseCases({
+  gateway,
+  fallback,
+  overview,
+  catalogById,
+  snapshots,
+  clock,
+  propose: proposeUseCase,
+  // Re-derives display statistics for a scoped window; the overview use case owns
+  // the pipeline, and injecting it keeps this module free of a second copy.
+  displaySeries: toDisplay,
+  log = () => {},
+  options = {},
+}) {
+  const maxAttempts = options.maxAttempts ?? 2
+  const cacheMinutes = options.cacheMinutes ?? AI_CACHE_MINUTES
+  const digestBudget = options.digestBudget ?? 8000
+
+  /**
+   * Build the digest entries for a request.
+   *
+   * `detail: false` skips the per-indicator series fan-out and returns entries
+   * with only the metrics' headline numbers. Callers use it to render a compact
+   * inventory of the whole panel — "what else is here" — which must not cost one
+   * series fetch per indicator on every discussion click.
+   *
+   * @param {{ range?: string, indicators?: string[], groups?: string[], limit?: number, noteworthy?: number, detail?: boolean }} request - request.
+   * @returns {Promise<{ entries: object[], range: object, metrics: object[], noteworthy: object[] }>} digest input.
+   */
+  async function buildEntries(request) {
+    const result = await overview.overview({
+      range: request.range ?? '1Y',
+      ids: request.indicators,
+      groups: request.groups,
+      limit: request.noteworthy ?? 5,
+    })
+    const wanted = new Set(request.indicators ?? result.metrics.map((metric) => metric.indicatorId))
+    const entries = []
+    for (const metric of result.metrics) {
+      if (!wanted.has(metric.indicatorId)) continue
+      const indicator = catalogById[metric.indicatorId]
+      if (indicator === undefined) continue
+      entries.push({
+        indicator,
+        stats: {
+          latest: metric.latest,
+          latestAt: metric.latestAt,
+          changeAbs: metric.changeAbs,
+          changePct: metric.changePct,
+          yoy: metric.yoy,
+          mean: undefined,
+          min: undefined,
+          max: undefined,
+          stdDev: undefined,
+          missingCount: 0,
+          count: metric.pointCount,
+        },
+        points: [],
+        status: metric.status,
+        score: metric.score,
+        sourceRef: metric.sourceRef,
+      })
+    }
+    // The digest renders the same numbers the cards show, so a viewer can check
+    // any claim in the answer against the panel.
+    if (request.detail === false) return { entries, range: result.range, metrics: result.metrics, noteworthy: result.noteworthy ?? [] }
+    const detailed = await Promise.all(
+      entries.map(async (entry) => {
+        const series = await overview.seriesFor(entry.indicator.id, result.range)
+        return series === undefined ? entry : { ...entry, stats: series.stats ?? entry.stats, points: series.points ?? [] }
+      }),
+    )
+    // Statistics and the published point list must describe ONE window. Reading
+    // them from the whole fetched series made the digest announce
+    // `mean=2616.73 points=250 missing=2577` — numbers from 2004 — beside 250
+    // points from the last year, and an agent then reported the contradiction
+    // instead of analysing the indicator. Scoped here, every published number
+    // describes the range the panel is showing, while the fetched tail still
+    // feeds whatever lookback a statistic needs (YoY keeps its earlier points).
+    const scoped = detailed.map((entry) => {
+      if (typeof toDisplay !== 'function') return entry
+      const points = (entry.points ?? []).filter((point) => inRange(point.t, result.range))
+      if (points.length === 0) return entry
+      return { ...entry, points, stats: toDisplay(entry.indicator, { points }).stats ?? entry.stats }
+    })
+    return { entries: scoped, range: result.range, metrics: result.metrics, noteworthy: result.noteworthy ?? [] }
+  }
+
+  /**
+   * Render the triggered attention rules as digest text.
+   *
+   * "Worth watching today" is a *rule outcome*, not a measurement, so it is not
+   * part of any indicator block — but it is the reason a reader opens the panel
+   * at all, and an analysis that cannot see it answers the wrong question. The
+   * same block feeds the overall-analysis digest and the discussion context a
+   * noteworthy item's button opens.
+   *
+   * @param {Array<{ indicatorId: string, label?: { zh?: string }, reasons?: object[], score?: number, status?: string }>} noteworthy - panel noteworthy items.
+   * @returns {string} digest section, or '' when nothing fired.
+   */
+  function buildNoteworthyText(noteworthy) {
+    const items = noteworthy ?? []
+    if (items.length === 0) return ''
+    const lines = ['## 今日值得关注（规则触发，非用户提问）']
+    for (const item of items) {
+      const reasons = (item.reasons ?? [])
+        .map((reason) => reason?.reason?.zh ?? reason?.ruleId)
+        .filter((text) => typeof text === 'string' && text !== '')
+      lines.push(`- ${item.indicatorId} | ${item.label?.zh ?? item.indicatorId} | 关注分 ${formatScore(item.score)} | ${item.status ?? 'unknown'}`)
+      if (reasons.length > 0) lines.push(`  触发原因: ${reasons.join('；')}`)
+    }
+    return lines.join('\n')
+  }
+
+  /**
+   * One decimal, so the digest text is stable across renders.
+   *
+   * @param {number} [value] - score.
+   * @returns {string} formatted score.
+   */
+  function formatScore(value) {
+    return Number.isFinite(value) ? (Math.round(value * 10) / 10).toFixed(1) : '0.0'
+  }
+
+  /**
+   * Read a cached AI result.
+   *
+   * @param {string} key - cache key.
+   * @returns {Promise<object|undefined>} cached result.
+   */
+  async function readCache(key) {
+    const entry = await snapshots.read(`ai|${key}`)
+    if (entry === undefined) return undefined
+    const age = clock.now().getTime() - new Date(entry.storedAt).getTime()
+    if (age > cacheMinutes * 60_000) return undefined
+    return entry.payload
+  }
+
+  /**
+   * Store an AI result.
+   *
+   * @param {string} key - cache key.
+   * @param {object} payload - result.
+   * @returns {Promise<void>} completion.
+   */
+  async function writeCache(key, payload) {
+    await snapshots.write(`ai|${key}`, payload, { ttlMs: cacheMinutes * 60_000, at: clock.now().toISOString() })
+  }
+
+  /**
+   * Run one operation through the gateway with validation, retry and fallback.
+   *
+   * @param {object} input - invocation.
+   * @param {'explain'|'summarize'|'answer'|'overview'} input.op - operation.
+   * @param {object} input.request - operation request.
+   * @param {object} input.digestInput - digest entries and range.
+   * @param {(gateway: object, violations?: string[]) => Promise<object>} input.invoke - gateway call.
+   * @param {(violations?: string[]) => Promise<object>} input.fallbackCall - deterministic call.
+   * @param {string} input.cacheKeyValue - cache identity.
+   * @returns {Promise<object>} 'AiResult'.
+   */
+  async function runValidated({ op, digestInput, digestText, invoke, fallbackCall, cacheKeyValue, request = {} }) {
+    const cached = await readCache(cacheKeyValue)
+    if (cached !== undefined) {
+      log('ai cache hit', { op, key: cacheKeyValue })
+      return { ...cached, cached: true }
+    }
+    const data = buildValidationData(digestInput.entries)
+    let violations
+    let attempt = 0
+    let lastVerdict
+    while (attempt < maxAttempts) {
+      attempt += 1
+      const result = await invoke(gateway, violations)
+      if (result?.mode === 'deterministic') {
+        const payload = { ...result, cached: false }
+        await writeCache(cacheKeyValue, payload)
+        return payload
+      }
+      // An empty answer is a provider failure, not a citation violation: retrying
+      // the same call will not help, so degrade immediately and carry the reason.
+      if ((result?.markdown ?? '') === '') {
+        lastVerdict = {
+          ok: false,
+          violations: [{ kind: 'empty-answer', detail: result?.emptyReason?.detail ?? '模型返回了空回答' }],
+          usedPoints: [],
+          insufficient: undefined,
+        }
+        break
+      }
+      const verdict = validateAnswer({ text: result.markdown, data, echoOf: request.question, digestText })
+      lastVerdict = verdict
+      if (decideAction(verdict, attempt, maxAttempts) === 'accept') {
+        const payload = {
+          ...result,
+          usedPoints: verdict.usedPoints.length > 0 ? verdict.usedPoints : (result.usedPoints ?? []),
+          cached: false,
+        }
+        await writeCache(cacheKeyValue, payload)
+        return payload
+      }
+      if (decideAction(verdict, attempt, maxAttempts) === 'retry') {
+        violations = violationLines(verdict.violations)
+        log('ai output failed validation, retrying', { op, violations })
+        continue
+      }
+    }
+    // Two failed attempts: degrade rather than show unverifiable text.
+    log('ai output failed validation, degrading to deterministic', { op, violations: violationLines(lastVerdict?.violations ?? []) })
+    const degraded = await fallbackCall(violationLines(lastVerdict?.violations ?? []))
+    const payload = {
+      ...degraded,
+      mode: 'deterministic',
+      degradedFrom: gateway.describe?.().mode ?? 'llm',
+      violations: lastVerdict?.violations ?? [],
+      degradedReason: lastVerdict?.violations?.[0]?.detail ?? undefined,
+      cached: false,
+    }
+    await writeCache(cacheKeyValue, payload)
+    return payload
+  }
+
+  /**
+   * Explain one indicator.
+   *
+   * @param {{ indicatorId: string, range?: string }} request - request.
+   * @returns {Promise<object>} 'AiResult'.
+   */
+  async function explain(request) {
+    const indicator = catalogById[request.indicatorId]
+    if (indicator === undefined) {
+      return {
+        markdown: `数据不足：目录中没有指标 ${request.indicatorId}。`,
+        usedPoints: [],
+        insufficient: 'unknown indicator',
+        mode: gateway.describe?.().mode ?? 'deterministic',
+        fingerprint: fingerprint(`explain|${request.indicatorId}|unknown`),
+      }
+    }
+    const digestInput = await buildEntries({ range: request.range, indicators: [request.indicatorId] })
+    const digest = buildDigest(digestInput.entries, { budget: digestBudget, title: `指标解析：${indicator.label.zh}`, range: digestInput.range })
+    const cacheKeyValue = `explain|${request.indicatorId}|${digestInput.range.from}|${digestInput.range.to}|${fingerprint(digest.text)}`
+    return runValidated({
+      op: 'explain',
+      digestInput,
+      digestText: digest.text,
+      cacheKeyValue,
+      invoke: async (activeGateway, violations) => {
+        const prompt = buildExplainPrompt({ digest: digest.text, indicatorId: indicator.id, label: indicator.label.zh, range: digestInput.range, violations })
+        return activeGateway.explain({
+          ...request,
+          ...prompt,
+          // The raw request carries the preset *string*; the prompt and every
+          // gateway expect the resolved `{ from, to }`, so the raw one must not
+          // win. It did, and the deterministic answer printed
+          // "区间：undefined .. undefined".
+          range: digestInput.range,
+          entries: digestInput.entries,
+          digest: digest.text,
+        })
+      },
+      fallbackCall: async () =>
+        fallback.explain({ entries: digestInput.entries, indicatorId: request.indicatorId, range: digestInput.range }),
+    })
+  }
+
+  /**
+   * Summarise a period.
+   *
+   * @param {{ range?: string, indicators?: string[] }} request - request.
+   * @returns {Promise<object>} 'AiResult'.
+   */
+  async function summarize(request) {
+    const digestInput = await buildEntries({ range: request.range, indicators: request.indicators })
+    const digest = buildDigest(digestInput.entries, { budget: digestBudget, title: '时段总结', range: digestInput.range })
+    const cacheKeyValue = `summary|${digestInput.range.from}|${digestInput.range.to}|${fingerprint(digest.text)}`
+    return runValidated({
+      op: 'summarize',
+      digestInput,
+      digestText: digest.text,
+      cacheKeyValue,
+      invoke: async (activeGateway, violations) => {
+        const prompt = buildSummaryPrompt({ digest: digest.text, range: digestInput.range, violations })
+        return activeGateway.summarize({ ...request, ...prompt, range: digestInput.range, entries: digestInput.entries, digest: digest.text })
+      },
+      fallbackCall: async () => fallback.summarize({ entries: digestInput.entries, range: digestInput.range }),
+    })
+  }
+
+  /**
+   * Answer a question from panel data only.
+   *
+   * @param {{ question: string, range?: string }} request - request.
+   * @returns {Promise<object>} 'AiResult'.
+   */
+  async function ask(request) {
+    const digestInput = await buildEntries({ range: request.range })
+    // Resolve the question against the catalog first: this is what lets the
+    // deterministic fallback answer "数据不足" instead of picking a weak match.
+    digestInput.matches = searchIndicators(request.question, { limit: 5 }).matches.map((entry) => ({ ...entry.indicator, matchScore: entry.score }))
+    const digest = buildDigest(digestInput.entries, { budget: digestBudget, title: '面板数据', range: digestInput.range })
+    const cacheKeyValue = `answer|${fingerprint(request.question)}|${digestInput.range.from}|${digestInput.range.to}|${fingerprint(digest.text)}`
+    return runValidated({
+      op: 'answer',
+      digestInput,
+      digestText: digest.text,
+      cacheKeyValue,
+      request,
+      invoke: async (activeGateway, violations) => {
+        const prompt = buildAnswerPrompt({ digest: digest.text, question: request.question, range: digestInput.range, violations })
+        return activeGateway.answer({ ...request, ...prompt, range: digestInput.range, entries: digestInput.entries, digest: digest.text })
+      },
+      fallbackCall: async () =>
+        fallback.answer({ entries: digestInput.entries, question: request.question, range: digestInput.range, matches: digestInput.matches }),
+    })
+  }
+
+  /**
+   * Propose an indicator definition.
+   *
+   * @param {{ text: string, verify?: boolean }} request - request.
+   * @returns {Promise<object>} proposal.
+   */
+  async function propose(request) {
+    if (proposeUseCase === undefined) {
+      return { candidates: [], unsupported: [{ request: request.text, reason: 'propose use case is not wired' }], rejected: [], mode: 'deterministic' }
+    }
+    return proposeUseCase.propose(request)
+  }
+
+  /**
+   * Analyse the panel as a whole — or one group of it — with the same rules.
+   *
+   * The single-indicator path answers "what does this number mean". This one
+   * answers "what is going on", so its digest carries every observable in scope
+   * *and* the triggered attention rules, and the prompt asks for cross-indicator
+   * reading rather than a restatement of one series.
+   *
+   * @param {{ range?: string, groups?: string[], indicators?: string[], limit?: number }} request - request.
+   * @returns {Promise<object>} 'AiResult' plus `{ scope, indicators, noteworthy }`.
+   */
+  async function overviewAnalysis(request = {}) {
+    const groups = Array.isArray(request.groups) && request.groups.length > 0 ? request.groups : undefined
+    const digestInput = await buildEntries({
+      range: request.range,
+      groups,
+      indicators: request.indicators,
+      limit: request.limit,
+      noteworthy: request.limit,
+    })
+    const scope = groups === undefined ? 'ALL' : groups.join('+')
+    const noteworthyText = buildNoteworthyText(digestInput.noteworthy)
+    const title = `整体分析：${SCOPE_LABELS[scope] ?? scope}`
+    const digest = buildDigest(digestInput.entries, {
+      budget: digestBudget,
+      title,
+      range: digestInput.range,
+      ...(noteworthyText === '' ? {} : { extra: noteworthyText }),
+    })
+    const cacheKeyValue = `overview|${scope}|${digestInput.range.from}|${digestInput.range.to}|${fingerprint(digest.text)}`
+    const result = await runValidated({
+      op: 'overview',
+      digestInput,
+      digestText: digest.text,
+      cacheKeyValue,
+      invoke: async (activeGateway, violations) => {
+        const prompt = buildOverviewPrompt({
+          digest: digest.text,
+          scope: SCOPE_LABELS[scope] ?? scope,
+          range: digestInput.range,
+          indicatorCount: digestInput.entries.length,
+          noteworthyCount: digestInput.noteworthy.length,
+          violations,
+        })
+        return activeGateway.summarize({ ...request, ...prompt, range: digestInput.range, entries: digestInput.entries, digest: digest.text })
+      },
+      fallbackCall: async () => fallback.summarize({ entries: digestInput.entries, range: digestInput.range }),
+    })
+    return {
+      ...result,
+      scope,
+      scopeLabel: SCOPE_LABELS[scope] ?? scope,
+      indicators: digestInput.entries.map((entry) => entry.indicator.id),
+      noteworthy: digestInput.noteworthy.map((item) => item.indicatorId),
+      digestIncluded: digest.included,
+    }
+  }
+
+  /**
+   * @returns {{ mode: string, provider?: string, model?: string, cacheMinutes: number }} description.
+   */
+  function describe() {
+    return { ...(gateway.describe?.() ?? { mode: 'deterministic' }), cacheMinutes }
+  }
+
+  return { explain, summarize, ask, overviewAnalysis, propose, describe, buildEntries, buildNoteworthyText }
+}

package/lib/app/health.js

@@ -0,0 +1,77 @@
+/**
+ * The health use case: "which sources are working right now?" (docs/06 §5).
+ *
+ * @module app/health
+ */
+import { listCapabilities } from '../sources/registry.js'
+
+/**
+ * Create the health use case.
+ *
+ * @param {object} deps - dependencies.
+ * @param {object} deps.overview - the overview use case (provides source health).
+ * @param {import('../ports/clock.js').Clock} deps.clock - clock.
+ * @param {(msg: string, meta?: object) => void} [deps.log] - logger.
+ * @param {{ adapters?: () => Array<{ id: string, label: string, capabilities: any[] }> }} [deps.registry] - adapter registry access.
+ * @returns {object} health use case.
+ */
+export function createHealthUseCase({ overview, clock, log = () => {}, registry = { adapters: listCapabilities } }) {
+  /**
+   * Report per-source status.
+   *
+   * @param {{ probe?: boolean, range?: string, groups?: string[], ids?: string[] }} [request] - request.
+   * @returns {Promise<object>} '{ ok, sources, generatedAt, aiMode, degraded }'.
+   */
+  async function health(request = {}) {
+    let sourceHealth = {}
+    let errors = []
+    let aiMode = 'deterministic'
+    const probing = request.probe === true || (Array.isArray(request.ids) && request.ids.length > 0)
+    try {
+      // A probe re-fetches every indicator in scope, ignoring the cache, so it
+      // reports whether the *upstream* answers right now rather than what is
+      // already stored. Narrowing by `ids` keeps a single-source check cheap.
+      const result = await overview.overview({
+        // A probe asks "can this deployment fetch right now", so it must touch
+        // every observable: a 1Y window leaves sources whose only indicator has
+        // older observations untested, and they then report a misleading `null`.
+        range: request.range ?? (probing ? 'MAX' : '1Y'),
+        limit: 1,
+        groups: request.groups,
+        ids: request.ids,
+        force: probing,
+      })
+      sourceHealth = result.sources
+      errors = result.errors
+    } catch (error) {
+      // Health must never itself fail: a broken data layer is exactly what it
+      // is supposed to report.
+      log('health overview failed', { message: error?.message ?? String(error) })
+      errors = [{ kind: 'internal', detail: String(error?.message ?? error) }]
+    }
+
+    const sources = registry.adapters().map((adapter) => {
+      const status = sourceHealth[adapter.id]
+      return {
+        adapterId: adapter.id,
+        label: adapter.label,
+        capabilities: adapter.capabilities,
+        available: status === undefined ? null : status.failed === 0,
+        ok: status?.ok ?? 0,
+        degraded: status?.degraded ?? 0,
+        failed: status?.failed ?? 0,
+        lastSuccessAt: status?.lastSuccessAt,
+      }
+    })
+
+    return {
+      ok: sources.every((source) => source.failed === 0),
+      sources,
+      errors,
+      aiMode,
+      generatedAt: clock.now().toISOString(),
+    }
+  }
+
+  return { health }
+}