dsh-plugin-show-me-data 0.1.0

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "dsh-plugin-show-me-data",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Show Me Data — global macro/rates/equity/bond indicator radar for DeepSeek Harness (host half + browser panel)",
+  "license": "MIT",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "plugin",
+    "macro",
+    "indicators",
+    "dashboard",
+    "fred",
+    "worldbank",
+    "candlestick"
+  ],
+  "author": "hhhcbw",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hhhcbw/dsh-plugin-show-me-data.git"
+  },
+  "homepage": "https://github.com/hhhcbw/dsh-plugin-show-me-data#readme",
+  "bugs": {
+    "url": "https://github.com/hhhcbw/dsh-plugin-show-me-data/issues"
+  },
+  "main": "lib/host.js",
+  "exports": {
+    ".": "./lib/host.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ]
+    }
+  },
+  "files": [
+    "lib",
+    "src",
+    "docs",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\"",
+    "test:net": "RUN_NET=1 node --test \"test/net/*.test.js\"",
+    "test:boot": "RUN_BOOT=1 node --test \"test/net/boot.test.js\"",
+    "coverage": "node --test --experimental-test-coverage \"test/**/*.test.js\"",
+    "build": "node scripts/build-client.mjs && node scripts/build-host.mjs",
+    "prepublishOnly": "node scripts/build-client.mjs && node scripts/build-host.mjs && node --test \"test/**/*.test.js\"",
+    "record": "RUN_NET=1 node scripts/record-fixtures.mjs",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/app/ai-deterministic.js

@@ -0,0 +1,327 @@
+/**
+ * The deterministic AI gateway — the offline product path (docs/06 §1).
+ *
+ * This is **not a mock**: when no LLM is configured, the panel still explains,
+ * summarises and answers, using the same digest the model would have received
+ * and citing the exact values it cites. Every result is labelled
+ * 'mode: 'deterministic'' so the user always knows which one they are reading.
+ *
+ * @module app/ai-deterministic
+ */
+import { fingerprint } from '../core/insight/rank.js'
+import { formatNumber } from '../core/insight/digest.js'
+
+/** Marker the UI renders as 「确定性摘要模式」. */
+export const MODE = 'deterministic'
+
+/**
+ * Below this score a catalog hit is too weak to present as a candidate.
+ *
+ * Measured against the shipped catalog: a real question about a catalog
+ * indicator scores 96-310 (label and alias hits), while an incidental token
+ * overlap - asking about tomorrow's oil price and hitting the WTI series on the
+ * word 油 - scores 38. The floor therefore sits between the two, so an
+ * unanswerable question gets "数据不足" instead of a price.
+ */
+export const WEAK_MATCH_SCORE = 60
+
+/**
+ * Floor for relevance computed against digest entries by {@link matchEntries}.
+ *
+ * The two scales are not comparable: a catalog search (core/indicators/resolve)
+ * weighs exact ids and aliases and scores a real hit 96-310, while the local
+ * digest matcher is additive token overlap and scores the same hit around 7.
+ * Using one number for both would either drop real answers or keep weak ones,
+ * so each path carries its own floor.
+ */
+export const WEAK_ENTRY_SCORE = 3
+
+/**
+ * Build the cited points for one digest entry.
+ *
+ * @param {object} entry - digest entry.
+ * @returns {Array<{ indicatorId: string, t: string, v: number, sourceRefUrl: string }>} cited points.
+ */
+function citesOf(entry) {
+  const stats = entry.stats ?? {}
+  const points = []
+  if (typeof stats.latest === 'number' && typeof stats.latestAt === 'string') {
+    points.push({ indicatorId: entry.indicator.id, t: stats.latestAt, v: stats.latest, sourceRefUrl: entry.sourceRef?.url })
+  }
+  if (typeof stats.prev === 'number' && entry.points?.length >= 2) {
+    const previous = entry.points[entry.points.length - 2]
+    points.push({ indicatorId: entry.indicator.id, t: previous.t, v: previous.v, sourceRefUrl: entry.sourceRef?.url })
+  }
+  return points
+}
+
+/**
+ * Create the deterministic gateway.
+ *
+ * @returns {object} 'AiGateway' implementation.
+ */
+export function createDeterministicGateway() {
+  /**
+   * Explain one indicator without a model.
+   *
+   * @param {{ entries: object[], indicatorId: string, range?: object }} request - request.
+   * @returns {Promise<object>} 'AiResult'.
+   */
+  async function explain({ entries, indicatorId, range }) {
+    const entry = (entries ?? []).find((candidate) => candidate.indicator.id === indicatorId)
+    if (entry === undefined) {
+      return {
+        markdown: '数据不足：没有找到该指标在当前范围内的观测，无法生成解析。',
+        usedPoints: [],
+        insufficient: '该指标在当前范围内没有可用观测',
+        mode: MODE,
+        fingerprint: fingerprint(`explain|${indicatorId}|empty`),
+      }
+    }
+    const { indicator, stats } = entry
+    const decimals = indicator.display?.decimals ?? 2
+    const lines = []
+    lines.push(`### ${indicator.label.zh}（${indicator.label.en}）`)
+    lines.push('')
+    if (stats === undefined) {
+      return {
+        markdown: `${lines.join('\n')}\n数据不足：该指标在本范围内没有任何可用观测。`,
+        usedPoints: [],
+        insufficient: '该指标在本范围内没有可用观测',
+        mode: MODE,
+        fingerprint: fingerprint(`explain|${indicatorId}|nostats`),
+      }
+    }
+    lines.push(
+      `**事实**：最新观测为 ${formatNumber(stats.latest, decimals)}${indicator.unit}（${stats.latestAt}）` +
+        `[${indicator.id}@${stats.latestAt}, ${stats.latest}]。`,
+    )
+    if (stats.changeAbs !== undefined) {
+      lines.push(
+        `- 较上期变化 ${stats.changeAbs >= 0 ? '+' : ''}${formatNumber(stats.changeAbs, decimals)}${indicator.unit}` +
+          (stats.changePct === undefined ? '' : `（${formatNumber(stats.changePct, 1)}%）`),
+      )
+    }
+    if (stats.yoy !== undefined) lines.push(`- 同比 ${formatNumber(stats.yoy, 1)}%`)
+    lines.push(`- 口径：${indicator.freq} 频，单位 ${indicator.unit}${indicator.seasonal === 'SA' ? '，季调' : ''}`)
+    if (indicator.notes?.zh) lines.push(`- 说明：${indicator.notes.zh}`)
+    if (stats.percentile !== undefined) {
+      lines.push(`- 分位：最新值位于本区间 ${formatNumber(stats.percentile * 100, 0)}% 分位`)
+    }
+    if (stats.zScoreLatestChange !== undefined) {
+      lines.push(`- 变化强度：最近一次变化为 ${formatNumber(stats.zScoreLatestChange, 1)}σ`)
+    }
+    if (range !== undefined) lines.push(`- 区间：${range.from} .. ${range.to}`)
+    lines.push('')
+    lines.push('**可能的影响**（以下为规则化解读，不构成投资建议）：')
+    const polarity = indicator.display?.polarity
+    lines.push(
+      polarity === 'up-is-good'
+        ? '- 该指标上行通常被视为改善，下行为恶化；请结合其他指标交叉验证。'
+        : polarity === 'down-is-good'
+          ? '- 该指标下行通常被视为改善，上行为恶化；请结合其他指标交叉验证。'
+          : '- 该指标的方向本身不直接代表好坏，需要看它与其他变量（增长、通胀、政策）的相对关系。',
+    )
+    return {
+      markdown: lines.join('\n'),
+      usedPoints: citesOf(entry),
+      mode: MODE,
+      fingerprint: fingerprint(`explain|${indicatorId}|${range?.from ?? ''}|${range?.to ?? ''}|${stats.latest}`),
+    }
+  }
+
+  /**
+   * Summarise a period without a model.
+   *
+   * @param {{ entries: object[], range?: object, text?: string }} request - request; 'text' overrides the rendered body.
+   * @returns {Promise<object>} 'AiResult'.
+   */
+  async function summarize({ entries, range, text }) {
+    const markdown = text ?? renderFallback(entries, range)
+    const usedPoints = (entries ?? []).flatMap(citesOf)
+    if (usedPoints.length === 0) {
+      return {
+        markdown: '数据不足：当前没有任何可用的指标观测，无法生成时段总结。',
+        usedPoints: [],
+        insufficient: '本次没有任何可用观测',
+        mode: MODE,
+        fingerprint: fingerprint('summary|empty'),
+      }
+    }
+    return {
+      markdown,
+      usedPoints,
+      mode: MODE,
+      fingerprint: fingerprint(`summary|${range?.from ?? ''}|${range?.to ?? ''}|${usedPoints.length}`),
+    }
+  }
+
+  /**
+   * Answer a question using only the digest, deterministically.
+   *
+   * @param {{ entries: object[], question: string, range?: object, matches?: object[] }} request - request.
+   * @returns {Promise<object>} 'AiResult'.
+   */
+  async function answer({ entries, question, range, matches }) {
+    // The same confidence floor the propose path uses: a weak match must produce
+    // "数据不足" rather than an unrelated number.
+    // Only entries that were resolved through search carry a `matchScore`; a
+    // caller handing pre-selected digest entries is taken at its word.
+    // `matches` arrives from a catalog search (its own scale); otherwise the
+    // question is matched locally against the digest entries.
+    const floor = matches === undefined ? WEAK_ENTRY_SCORE : WEAK_MATCH_SCORE
+    const candidates = (matches ?? matchEntries(entries, question)).filter((entry) => {
+      // `matchScore` is relevance; `score` is the entry's attention score and
+      // must never be read as relevance.
+      const relevance = entry.matchScore ?? entry.score
+      return relevance === undefined || relevance >= floor
+    })
+    if (candidates.length === 0) {
+      return {
+        markdown:
+          `数据不足：面板中的数据无法回答「${question ?? ''}」。\n\n` +
+          '- 当前可用指标里没有与该问题相关的口径。\n' +
+          '- 可尝试：换一个更具体的指标名称（例如「美国 CPI 同比」「中国制造业 PMI」），或缩小时间范围。',
+        usedPoints: [],
+        insufficient: '问题超出面板数据覆盖范围',
+        mode: MODE,
+        fingerprint: fingerprint(`answer|${question ?? ''}|none`),
+      }
+    }
+    // Callers may hand either digest entries ({ indicator, stats, points }) or
+    // flat catalog matches ({ id, label, ... }); normalize to digest entries so
+    // a lookup path can never crash the answer.
+    const byId = new Map((entries ?? []).map((entry) => [entry.indicator?.id, entry]))
+    const top = candidates
+      .slice(0, 3)
+      .map((candidate) => byId.get(candidate.indicator?.id ?? candidate.id) ?? candidate)
+      .filter((candidate) => candidate.indicator !== undefined)
+    const lines = []
+    lines.push(`在面板数据范围内，与「${question}」最相关的是：`)
+    for (const entry of top) {
+      const decimals = entry.indicator.display?.decimals ?? 2
+      if (entry.stats === undefined) {
+        lines.push(`- ${entry.indicator.label.zh}：数据不足，本范围内没有观测。`)
+        continue
+      }
+      // The citation form is included so the deterministic answer satisfies the
+      // same validator the model's answer has to pass.
+      lines.push(
+        `- ${entry.indicator.label.zh}：最新 ${formatNumber(entry.stats.latest, decimals)}${entry.indicator.unit}（${entry.stats.latestAt}）` +
+          `[${entry.indicator.id}@${entry.stats.latestAt}, ${entry.stats.latest}]` +
+          (entry.stats.changeAbs === undefined ? '' : `，较上期 ${entry.stats.changeAbs >= 0 ? '+' : ''}${formatNumber(entry.stats.changeAbs, decimals)}`),
+      )
+    }
+    lines.push('')
+    lines.push('**依据**：以上数值均来自面板内的公开数据源，可在每条指标卡片的来源徽章处打开原始页面。')
+    lines.push('**数据边界**：只覆盖面板中列出的指标与时间范围；不包含新闻、事件与预测。')
+    return {
+      markdown: lines.join('\n'),
+      usedPoints: top.flatMap(citesOf),
+      mode: MODE,
+      fingerprint: fingerprint(`answer|${question ?? ''}|${top.map((entry) => entry.indicator.id).join(',')}`),
+    }
+  }
+
+  /**
+   * 'propose' without a model can only answer from the existing catalog.
+   *
+   * @param {{ request: string, matches?: object[] }} input - propose input.
+   * @returns {Promise<{ candidates: object[], unsupported: object[], mode: string }>} result.
+   */
+  async function propose({ request, matches = [] }) {
+    // Only a genuinely strong catalog hit becomes a candidate. A weak fuzzy match
+    // (asking for a German business-climate index and getting "US dollar index"
+    // because both contain 指数) must not be dressed up as an answer.
+    const confident = matches.filter((entry) => (entry.score ?? 0) >= WEAK_MATCH_SCORE)
+    if (confident.length > 0) {
+      const best = confident[0].indicator
+      return {
+        candidates: [
+          {
+            // The catalog definition is echoed whole: it already passed
+            // validateIndicatorDef in the catalog suite, and re-validating it
+            // through the propose gate would reject fields this echo omits
+            // (seasonal, notes) for no reason.
+            ...best,
+            fromCatalog: true,
+            confidence: Number(((matches[0].score ?? 0) / 150).toFixed(2)),
+            rationale: `目录检索命中已有指标 ${best.id}（确定性模式不做自然语言推理）。`,
+          },
+        ],
+        unsupported: [],
+        mode: MODE,
+      }
+    }
+    return {
+      candidates: [],
+      unsupported: [
+        {
+          request,
+          reason: '确定性摘要模式无法解析自然语言需求，也不会猜测数据源标识。',
+          alternatives: ['在指标目录中检索并手动添加', '配置 LLM 后重试对话式添加'],
+        },
+      ],
+      mode: MODE,
+    }
+  }
+
+  /**
+   * @returns {{ mode: string }} mode description.
+   */
+  function describe() {
+    return { mode: MODE }
+  }
+
+  return { explain, summarize, answer, propose, describe }
+}
+
+/**
+ * Rank digest entries against a free-text question.
+ *
+ * @param {object[]} entries - digest entries.
+ * @param {string} question - question text.
+ * @returns {object[]} matching entries, best first.
+ */
+export function matchEntries(entries, question) {
+  const text = String(question ?? '').toLowerCase()
+  if (text.trim() === '') return []
+  return (entries ?? [])
+    .map((entry) => {
+      const haystack = [entry.indicator.id, entry.indicator.label.zh, entry.indicator.label.en, ...(entry.indicator.aliases ?? [])]
+        .join(' ')
+        .toLowerCase()
+      let score = 0
+      for (const token of text.split(/[\s,，。？?、]+/).filter((token) => token.length >= 2)) {
+        if (haystack.includes(token)) score += 2
+      }
+      for (const alias of entry.indicator.aliases ?? []) {
+        if (text.includes(alias.toLowerCase())) score += 3
+      }
+      if (text.includes(entry.indicator.label.zh)) score += 4
+      return { entry, score }
+    })
+    .filter((candidate) => candidate.score > 0)
+    .sort((a, b) => b.score - a.score || b.entry.indicator.importance - a.entry.indicator.importance)
+    .map((candidate) => ({ ...candidate.entry, matchScore: candidate.score }))
+}
+
+/**
+ * The plain-text fallback summary used when 'core/insight/digest' did not
+ * already render one.
+ *
+ * @param {object[]} entries - digest entries.
+ * @param {{ from: string, to: string }} [range] - range.
+ * @returns {string} markdown.
+ */
+function renderFallback(entries, range) {
+  if (!entries || entries.length === 0) return '数据不足：当前没有任何可用的指标观测。'
+  const lines = ['### 时段数据摘要']
+  if (range !== undefined) lines.push(`区间：${range.from} .. ${range.to}`)
+  for (const entry of entries.slice(0, 10)) {
+    const decimals = entry.indicator.display?.decimals ?? 2
+    lines.push(`- ${entry.indicator.label.zh}：${formatNumber(entry.stats?.latest, decimals)}${entry.indicator.unit}（${entry.stats?.latestAt ?? 'n/a'}）`)
+  }
+  lines.push('- 数据来自公开源，仅供研究参考，不构成投资建议。')
+  return lines.join('\n')
+}

package/src/app/ai-validate.js

@@ -0,0 +1,284 @@
+/**
+ * Output validation — the enforcement point that turns "AI explanation" into a
+ * verifiable feature (docs/06 §3).
+ *
+ * Three checks, in order of severity:
+ * 1. every '[id@date, value]' citation must match a real digest point;
+ * 2. every number in the text must be traceable to the digest (or be a
+ *    whitelisted shape such as a year, a section ordinal or a percentage sign);
+ * 3. the answer must not claim the future or give advice.
+ *
+ * A violation never reaches the user: the caller retries once with the feedback,
+ * then degrades to the deterministic summary.
+ *
+ * @module app/ai-validate
+ */
+
+/** Citation syntax the model is told to use: '[id@date, value]'. */
+export const CITATION_RE = /\[([a-z0-9]+(?:\.[a-z0-9]+)+)@(\d{4}-\d{2}-\d{2})\s*,\s*(-?\d+(?:\.\d+)?)\s*\]/g
+
+/** Numbers that are allowed without a data source, with the reason why. */
+export const NUMBER_WHITELIST = [
+  { pattern: /^(19|20)\d{2}$/, reason: 'year' },
+  { pattern: /^\d{4}-\d{2}-\d{2}$/, reason: 'date' },
+  { pattern: /^(0|1|2|3|4|5|6|7|8|9|10)$/, reason: 'small ordinal' },
+  { pattern: /^(100|12|4|3|2|1)$/, reason: 'structural constant (percent/month/quarter counts)' },
+]
+
+/**
+ * Whether a number is the difference between two published values.
+ *
+ * "从 4.5% 到 4.1%，两端相差 0.4 个百分点" is the whole point of a data panel,
+ * and both observations are cited in the same sentence. Refusing it degraded
+ * correct answers; accepting it still refuses a number that appears nowhere in
+ * the data (a valuation multiple, a policy rate the panel never fetched).
+ *
+ * @param {number} value - number found in the text.
+ * @param {number[]} candidates - published numbers.
+ * @param {number} [tolerance] - rounding tolerance for the difference.
+ * @returns {boolean} whether it is a difference of two published values.
+ */
+export function isPublishedDifference(value, candidates) {
+  // Tolerance follows the precision the digest prints: two readings quoted to
+  // one decimal are subtracted to one decimal by anyone reading them, so the
+  // allowance is half of that last digit and no more. A wider window would wave
+  // through a number that merely happens to sit near *some* difference.
+  const tolerance = 0.05 / 10 ** Math.max(0, decimalsOf(value) - 1)
+  for (const a of candidates) {
+    if (!Number.isFinite(a)) continue
+    for (const b of candidates) {
+      if (!Number.isFinite(b)) continue
+      if (Math.abs(Math.abs(a - b) - value) <= tolerance) return true
+    }
+  }
+  return false
+}
+
+/**
+ * Digits after the decimal point in the *written* form of a number.
+ *
+ * @param {number} value - number from the text.
+ * @returns {number} decimal places (0 for an integer).
+ */
+function decimalsOf(value) {
+  const text = String(value)
+  const dot = text.indexOf('.')
+  return dot === -1 ? 0 : text.length - dot - 1
+}
+
+/** Phrases that assert a prediction or investment advice. */
+export const FORBIDDEN_PATTERNS = [
+  { pattern: /必然|一定会|肯定会|毫无疑问/, reason: 'absolute wording' },
+  { pattern: /建议(买入|卖出|加仓|减仓|做多|做空)|买入信号|卖出信号/, reason: 'investment advice' },
+  // A modal future marker followed by a direction verb. Deliberately not
+  // date-anchored: in practice any `会/将 + 涨跌` in a data panel's output is a
+  // forecast, and requiring a nearby date made the check miss the common
+  // phrasing `明天会上涨`.
+  { pattern: /(?:会|将)\s*(?:继续)?\s*(?:上涨|涨|下跌|跌|上行|下行|走高|走低|突破|跌破)/, reason: 'price prediction' },
+  { pattern: /目标价|看到\d+点|涨到\d+|跌到\d+/, reason: 'price target' },
+]
+
+/**
+ * One digest entry flattened for validation.
+ *
+ * @typedef {Object} ValidationData
+ * @property {Record<string, { values: number[], dates: string[], stats: number[] }>} byIndicator
+ * @property {number[]} counts - observation counts the digest states about itself.
+ */
+
+/**
+ * Build the validation index from digest entries.
+ *
+ * @param {Array<{ indicator: object, stats?: object, points?: Array<{ t: string, v: number }> }>} entries - digest entries.
+ * @returns {ValidationData} validation data.
+ */
+export function buildValidationData(entries) {
+  const byIndicator = {}
+  // Counts the digest itself publishes ("points=13 missing=2"). They describe the
+  // series rather than measure it, so a model restating them is not inventing a
+  // number — refusing them would penalise it for reading our own output.
+  const counts = []
+  for (const entry of entries ?? []) {
+    const id = entry?.indicator?.id
+    if (typeof id !== 'string') continue
+    const bucket = byIndicator[id] ?? { values: [], dates: [], stats: [] }
+    for (const point of entry.points ?? []) {
+      bucket.values.push(point.v)
+      bucket.dates.push(point.t)
+    }
+    const stats = entry.stats ?? {}
+    for (const key of ['count', 'missingCount']) {
+      if (typeof stats[key] === 'number' && Number.isFinite(stats[key])) counts.push(stats[key])
+    }
+    counts.push((entry.points ?? []).length)
+    for (const key of ['latest', 'prev', 'changeAbs', 'changePct', 'yoy', 'mom', 'mean', 'min', 'max', 'stdDev', 'slope', 'zScoreLatestChange', 'percentile']) {
+      if (typeof stats[key] === 'number' && Number.isFinite(stats[key])) bucket.stats.push(stats[key])
+    }
+    if (typeof stats.latest === 'number') bucket.values.push(stats.latest)
+    if (typeof stats.latestAt === 'string') bucket.dates.push(stats.latestAt)
+    byIndicator[id] = bucket
+  }
+  return { byIndicator, counts }
+}
+
+/**
+ * Whether a number appears in the digest, within a display rounding tolerance.
+ *
+ * @param {number} value - the number found in the text.
+ * @param {number[]} candidates - digest numbers.
+ * @returns {boolean} whether it is traceable.
+ */
+export function matchesData(value, candidates) {
+  // Tolerance is deliberately tight: a number the model invented must not pass
+  // just because it is "close enough" to a real observation.
+  const tolerance = 1e-6
+  for (const candidate of candidates) {
+    if (!Number.isFinite(candidate)) continue
+    if (Math.abs(candidate - value) <= tolerance) return true
+    // The model is asked to round to `decimals`; accept any rounding of the value.
+    for (const decimals of [0, 1, 2, 3, 4]) {
+      if (Number(candidate.toFixed(decimals)) === value) return true
+    }
+    // Percentage points written without the sign, and unit-scaled forms
+    // (e.g. a percentage reported in decimal form).
+    if (Math.abs(candidate * 100 - value) <= tolerance) return true
+    if (Math.abs(candidate / 100 - value) <= tolerance) return true
+  }
+  return false
+}
+
+/**
+ * Extract every number literal from a text, with its position.
+ *
+ * @param {string} text - answer text.
+ * @returns {Array<{ raw: string, value: number, index: number }>} numbers.
+ */
+export function extractNumbers(text) {
+  const found = []
+  // Strip citations (they are validated separately) and calendar dates: the
+  // digits inside `2026-08-01` are not claims, and matching them produced
+  // nonsense violations like `-08`.
+  const cleaned = String(text ?? '')
+    .replace(CITATION_RE, ' ')
+    .replace(/\d{4}-\d{2}-\d{2}/g, ' ')
+    .replace(/\d{4}-\d{2}(?!\d)/g, ' ')
+  for (const match of cleaned.matchAll(/(?<![\d-])-?\d+(?:\.\d+)?/g)) {
+    found.push({ raw: match[0], value: Number(match[0]), index: match.index ?? 0 })
+  }
+  return found
+}
+
+/**
+ * Validate one answer against the digest.
+ *
+ * @param {object} input - validation input.
+ * @param {string} input.text - the model's answer.
+ * @param {ValidationData} input.data - digest index.
+ * @param {boolean} [input.allowEmptyCitations] - permit "数据不足" answers without citations.
+ * @param {string} [input.echoOf] - text the answer may legitimately contain verbatim (the user's question).
+ * @returns {{ ok: boolean, violations: Array<{ kind: string, detail: string, raw?: string }>, usedPoints: Array<{ indicatorId: string, t: string, v: number }>, insufficient: string|undefined }} verdict.
+ */
+export function validateAnswer({ text, data, allowEmptyCitations = true, echoOf, digestText }) {
+  const violations = []
+  const usedPoints = []
+  const source = typeof text === 'string' ? text : ''
+  const knownIds = new Set(Object.keys(data?.byIndicator ?? {}))
+
+  // An empty answer is never acceptable: the caller degrades to the
+  // deterministic summary instead of showing the user a blank panel.
+  if (source.trim() === '') {
+    return {
+      ok: false,
+      violations: [{ kind: 'empty-answer', detail: '模型返回了空回答' }],
+      usedPoints: [],
+      insufficient: undefined,
+    }
+  }
+
+  // 1) citations
+  for (const match of source.matchAll(CITATION_RE)) {
+    const [, indicatorId, date, rawValue] = match
+    const bucket = data?.byIndicator?.[indicatorId]
+    if (bucket === undefined) {
+      violations.push({ kind: 'unknown-indicator', detail: `引用不存在的指标 ${indicatorId}`, raw: match[0] })
+      continue
+    }
+    if (!bucket.dates.includes(date)) {
+      violations.push({ kind: 'unknown-date', detail: `${indicatorId} 在 ${date} 没有观测`, raw: match[0] })
+      continue
+    }
+    const value = Number(rawValue)
+    if (!matchesData(value, bucket.values)) {
+      violations.push({ kind: 'value-mismatch', detail: `${indicatorId}@${date} 的值 ${value} 与数据不符`, raw: match[0] })
+      continue
+    }
+    usedPoints.push({ indicatorId, t: date, v: value })
+  }
+
+  // 2) unsourced numbers
+  //
+  // "Sourced" means the digest shows it. Statistics and observations are the
+  // obvious part, but a label ("标普 500"), a field name and a computed delta all
+  // print there too, and a model restating any of them was being accused of
+  // inventing a number — which degraded perfectly good answers to the
+  // deterministic summary. Everything the digest prints is therefore traceable
+  // by definition, so the digest's own text is scanned as one more source.
+  const printed = extractNumbers(typeof digestText === 'string' ? digestText : '')
+  // Measurements only. `counts` and the digest text carry structural numbers
+  // ("points=250", a label's "500"), and differencing those against a reading
+  // would let an invented number through as "4.1 - 3".
+  const measurements = Object.values(data?.byIndicator ?? {}).flatMap((bucket) => [...bucket.values, ...bucket.stats])
+  const allNumbers = [...measurements, ...(data?.counts ?? []), ...printed.map((number) => number.value)]
+  for (const number of extractNumbers(source)) {
+    if (NUMBER_WHITELIST.some((entry) => entry.pattern.test(number.raw))) continue
+    if (matchesData(number.value, allNumbers)) continue
+    // Rounding tolerance, not a free pass: a reader comparing two published
+    // points does exactly this subtraction, and a published difference is
+    // arithmetic on our data rather than a fabricated observation.
+    if (isPublishedDifference(number.value, measurements)) continue
+    violations.push({ kind: 'unsourced-number', detail: `数字 ${number.raw} 无法在数据中找到来源`, raw: number.raw })
+  }
+
+  // 3) predictions and advice. A phrase the user themselves wrote is echoed by
+  // the answer ("数据不足：无法回答「明天油价会涨吗？」"), which is not the
+  // answer asserting a forecast — so the question's own wording is excused.
+  const echo = typeof echoOf === 'string' ? echoOf : ''
+  const withoutEcho = echo === '' ? source : source.split(echo).join(' ')
+  for (const rule of FORBIDDEN_PATTERNS) {
+    const match = rule.pattern.exec(withoutEcho)
+    if (match !== null) violations.push({ kind: 'forbidden-wording', detail: `${rule.reason}：${match[0]}`, raw: match[0] })
+  }
+
+  const insufficient = /数据不足/.test(source) ? source.match(/数据不足[^。\n]*/)?.[0] ?? '数据不足' : undefined
+  if (usedPoints.length === 0 && insufficient === undefined && !allowEmptyCitations) {
+    violations.push({ kind: 'no-citations', detail: '回答没有引用任何数据点' })
+  }
+  if (usedPoints.length === 0 && insufficient === undefined && knownIds.size > 0 && source.trim() !== '') {
+    violations.push({ kind: 'no-citations', detail: '回答没有引用任何数据点，也没有说明数据不足' })
+  }
+
+  return { ok: violations.length === 0, violations, usedPoints, insufficient }
+}
+
+/**
+ * Decide what to do with a verdict (docs/06 §3 rule 3).
+ *
+ * @param {{ ok: boolean }} verdict - validation verdict.
+ * @param {number} attempt - how many attempts have been made (1-based).
+ * @param {number} [maxAttempts] - retry budget.
+ * @returns {'accept'|'retry'|'degrade'} action.
+ */
+export function decideAction(verdict, attempt, maxAttempts = 2) {
+  if (verdict.ok) return 'accept'
+  return attempt < maxAttempts ? 'retry' : 'degrade'
+}
+
+/**
+ * Human-readable violation list for the retry prompt.
+ *
+ * @param {Array<{ detail: string }>} violations - violations.
+ * @returns {string[]} lines.
+ */
+export function violationLines(violations) {
+  return (violations ?? []).map((entry) => entry.detail)
+}