dsh-plugin-show-me-data 0.1.0

package/src/core/indicators/resolve.js

@@ -0,0 +1,196 @@
+/**
+ * Catalog search — natural-language and fuzzy lookup (docs/02 §2,
+ * 'core/indicators/resolve.js').
+ *
+ * Used by the panel's "add indicator" box and by the model's 'data_search'
+ * tool, so it must be total: no input throws, an empty query returns the
+ * highest-importance indicators, and a miss returns suggestions instead of an
+ * error.
+ *
+ * @module core/indicators/resolve
+ */
+import { CATALOG } from './catalog.js'
+
+/** How much each kind of hit is worth before the importance factor. */
+export const HIT_WEIGHTS = {
+  idExact: 100,
+  aliasExact: 80,
+  labelExact: 70,
+  aliasPrefix: 55,
+  labelPrefix: 45,
+  aliasPart: 30,
+  labelPart: 25,
+  tag: 18,
+  note: 10,
+  idPart: 8,
+}
+
+/**
+ * Normalize text for matching: lowercase, full-width digits and punctuation to
+ * ASCII, and whitespace collapsed.
+ *
+ * @param {string} text - input text.
+ * @returns {string} normalized text.
+ */
+export function normalize(text) {
+  return String(text ?? '')
+    .toLowerCase()
+    .replace(/[\uFF01-\uFF5E]/g, (char) => String.fromCharCode(char.charCodeAt(0) - 0xfee0))
+    .replace(/[\s\-_/,.、，。]+/g, ' ')
+    .trim()
+}
+
+/**
+ * Split a query into searchable tokens: latin words, digits, and CJK bigrams
+ * (a single Chinese character alone is usually too broad to be a token).
+ *
+ * @param {string} text - normalized text.
+ * @returns {string[]} tokens.
+ */
+export function tokenize(text) {
+  const normalized = normalize(text)
+  if (normalized === '') return []
+  const tokens = []
+  for (const part of normalized.split(' ')) {
+    if (part === '') continue
+    const cjk = /[\u4e00-\u9fff]/
+    if (cjk.test(part)) {
+      const chars = [...part]
+      // Single CJK characters are omitted on purpose: one character matches too
+      // many labels (曲/引/指 all appear somewhere) and turns a miss into noise.
+      // Bigrams are the useful unit for Chinese keyword matching.
+      for (let i = 0; i < chars.length - 1; i += 1) {
+        if (cjk.test(chars[i]) && cjk.test(chars[i + 1])) tokens.push(chars[i] + chars[i + 1])
+      }
+      if (chars.length === 1) tokens.push(chars[0])
+    } else {
+      tokens.push(part)
+    }
+  }
+  return [...new Set(tokens)]
+}
+
+/**
+ * Score one indicator against a query.
+ *
+ * @param {object} indicator - catalog entry.
+ * @param {string} rawQuery - user query.
+ * @returns {number} score (0 when nothing matches).
+ */
+export function scoreIndicator(indicator, rawQuery) {
+  const query = normalize(rawQuery)
+  if (query === '') return 0
+  const compact = query.replace(/ /g, '')
+  let score = 0
+
+  if (normalize(indicator.id) === query || indicator.id.toLowerCase() === compact) score += HIT_WEIGHTS.idExact
+  if (indicator.id.toLowerCase().includes(compact)) score += HIT_WEIGHTS.idPart
+
+  const labels = [indicator.label?.zh, indicator.label?.en].filter(Boolean).map(normalize)
+  for (const label of labels) {
+    if (label === query || label.replace(/ /g, '') === compact) score += HIT_WEIGHTS.labelExact
+    else if (label.startsWith(query)) score += HIT_WEIGHTS.labelPrefix
+    else if (label.includes(query)) score += HIT_WEIGHTS.labelPart
+  }
+
+  for (const alias of indicator.aliases ?? []) {
+    const value = normalize(alias)
+    if (value === query) score += HIT_WEIGHTS.aliasExact
+    else if (value.startsWith(query)) score += HIT_WEIGHTS.aliasPrefix
+    else if (value.includes(query)) score += HIT_WEIGHTS.aliasPart
+  }
+
+  for (const token of tokenize(rawQuery)) {
+    if (token.length < 2) continue
+    for (const alias of indicator.aliases ?? []) {
+      if (normalize(alias).includes(token)) score += HIT_WEIGHTS.aliasPart
+    }
+    for (const label of labels) {
+      if (label.includes(token)) score += HIT_WEIGHTS.labelPart
+    }
+    for (const tag of indicator.tags ?? []) {
+      if (normalize(tag).includes(token)) score += HIT_WEIGHTS.tag
+    }
+  }
+  // Notes and units count only as corroboration: on their own they make a long
+  // "why this indicator exists" paragraph match almost any query.
+  if (score > 0) {
+    for (const token of tokenize(rawQuery)) {
+      if (token.length < 2) continue
+      if (normalize(indicator.notes?.zh ?? '').includes(token)) score += HIT_WEIGHTS.note
+      if (normalize(indicator.unit).includes(token)) score += HIT_WEIGHTS.note
+    }
+  }
+  return score
+}
+
+/**
+ * Search the catalog.
+ *
+ * @param {string} query - user query (may be empty).
+ * @param {{ catalog?: object[], limit?: number, groups?: string[], minImportance?: number }} [options] - search options.
+ * @returns {{ matches: Array<{ indicator: object, score: number }>, suggestions: string[] }} matches plus suggestions on a miss.
+ */
+export function searchIndicators(query, { catalog = CATALOG, limit = 12, groups, minImportance } = {}) {
+  const pool = catalog.filter((indicator) => {
+    if (groups !== undefined && !groups.includes(indicator.group)) return false
+    if (minImportance !== undefined && indicator.importance < minImportance) return false
+    return true
+  })
+
+  if (normalize(query) === '') {
+    const matches = [...pool]
+      .sort((a, b) => b.importance - a.importance || a.id.localeCompare(b.id))
+      .slice(0, limit)
+      .map((indicator) => ({ indicator, score: indicator.importance }))
+    return { matches, suggestions: [] }
+  }
+
+  const scored = pool
+    .map((indicator) => ({ indicator, raw: scoreIndicator(indicator, query) }))
+    .filter((entry) => entry.raw > 0)
+
+  const matches = scored
+    .map((entry) => ({ indicator: entry.indicator, score: Math.round(entry.raw + entry.indicator.importance * 2) }))
+    .sort(
+      (a, b) =>
+        b.score - a.score ||
+        b.indicator.importance - a.indicator.importance ||
+        a.indicator.id.localeCompare(b.indicator.id),
+    )
+    .slice(0, limit)
+
+  if (matches.length > 0) return { matches, suggestions: [] }
+
+  const tokens = tokenize(query)
+  const suggestions = [...pool]
+    .map((indicator) => ({
+      indicator,
+      score: tokens.reduce(
+        (acc, token) =>
+          acc +
+          (normalize(indicator.label.zh).includes(token) || normalize(indicator.label.en).includes(token) ? 2 : 0) +
+          (indicator.tags ?? []).some((tag) => normalize(tag).includes(token)) ? 1 : 0,
+        0,
+      ),
+    }))
+    .sort((a, b) => b.score - a.score || b.indicator.importance - a.indicator.importance)
+    .slice(0, 5)
+    .map((entry) => entry.indicator.id)
+  return { matches: [], suggestions }
+}
+
+/**
+ * Resolve one query to its single best indicator, for conversational flows.
+ *
+ * @param {string} query - user query.
+ * @param {object} [options] - search options.
+ * @returns {{ indicator: object|undefined, ambiguous: object[] }} best match and the runner-ups.
+ */
+export function resolveIndicator(query, options = {}) {
+  const { matches } = searchIndicators(query, { ...options, limit: 5 })
+  if (matches.length === 0) return { indicator: undefined, ambiguous: [] }
+  const [best, ...rest] = matches
+  const ambiguous = rest.filter((entry) => entry.score === best.score).map((entry) => entry.indicator)
+  return { indicator: best.indicator, ambiguous }
+}

package/src/core/insight/digest.js

@@ -0,0 +1,250 @@
+/**
+ * Build the AI's data digest — the '<data>' block that keeps the model on a
+ * token budget and on real numbers (docs/06 §2.3).
+ *
+ * Two invariants the tests pin:
+ * 1. the digest never exceeds its character budget, and when it truncates it
+ *    **says so**, so the model knows it is looking at a subset;
+ * 2. every 'importance = 5' indicator makes it in regardless of score.
+ *
+ * @module core/insight/digest
+ */
+import { transformSuffix } from '../stats/series.js'
+
+/** Default character budget for one digest (docs/06 §2.3). */
+export const DIGEST_BUDGET = 8000
+
+/** How many observations per indicator are sent when the range is long. */
+export const DIGEST_POINTS = 12
+
+/**
+ * Format a number for the model: fixed decimals, no float noise, and a
+ * thousands separator only above 10 000 so small values stay copyable.
+ *
+ * @param {number|undefined} value - value.
+ * @param {number} [decimals] - decimal places.
+ * @returns {string} formatted value (''n/a'' when absent).
+ */
+export function formatNumber(value, decimals = 2) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 'n/a'
+  const fixed = value.toFixed(decimals)
+  const [int, fraction] = fixed.split('.')
+  const grouped = Math.abs(Number(int)) >= 10000 ? Number(int).toLocaleString('en-US') : int
+  return fraction === undefined ? grouped : `${grouped}.${fraction}`
+}
+
+/**
+ * Reduce a point series to at most 'count' representative points, always keeping
+ * the first, the last and the global extremes (docs/07 T5.3).
+ *
+ * @param {Array<{ t: string, v: number }>} points - ascending points.
+ * @param {number} [count] - target point count.
+ * @returns {Array<{ t: string, v: number }>} downsampled points.
+ */
+export function downsample(points, count = DIGEST_POINTS) {
+  if (!Array.isArray(points) || points.length <= count) return points ?? []
+  const first = points[0]
+  const last = points[points.length - 1]
+  let min = points[0]
+  let max = points[0]
+  for (const point of points) {
+    if (point.v < min.v) min = point
+    if (point.v > max.v) max = point
+  }
+  const keep = new Map()
+  keep.set(first.t, first)
+  keep.set(last.t, last)
+  keep.set(min.t, min)
+  keep.set(max.t, max)
+  const step = (points.length - 1) / (count - 1)
+  for (let i = 0; i < count; i += 1) {
+    const point = points[Math.round(i * step)]
+    if (point !== undefined) keep.set(point.t, point)
+  }
+  return [...keep.values()].sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0)).slice(0, count + 4)
+}
+
+/**
+ * One indicator's digest entry.
+ *
+ * @param {object} input - entry input.
+ * @param {object} input.indicator - catalog definition.
+ * @param {object} [input.stats] - computed stats.
+ * @param {Array<{ t: string, v: number }>} [input.points] - resolved points.
+ * @param {string} [input.status] - fresh/stale/error/missing.
+ * @param {object} [input.sourceRef] - provenance.
+ * @param {number} [input.score] - rule score (ordering hint only; never printed).
+ * @returns {string} one digest block.
+ */
+export function indicatorBlock({ indicator, stats, points = [], status = 'fresh', sourceRef }) {
+  const decimals = indicator.display?.decimals ?? 2
+  const suffix = transformSuffix(indicator.display)
+  const lines = []
+  const label = `${indicator.label.zh} / ${indicator.label.en}`
+  lines.push(`- ${indicator.id} | ${label} | ${indicator.unit}${suffix} | ${indicator.freq} | importance=${indicator.importance} | status=${status}`)
+  if (stats !== undefined && stats !== null) {
+    lines.push(
+      `  latest=${formatNumber(stats.latest, decimals)} @${stats.latestAt}` +
+        (stats.prev === undefined ? '' : ` prev=${formatNumber(stats.prev, decimals)}`) +
+        (stats.changeAbs === undefined ? '' : ` Δ=${formatNumber(stats.changeAbs, decimals)}`) +
+        (stats.changePct === undefined ? '' : ` Δ%=${formatNumber(stats.changePct, 1)}`) +
+        (stats.yoy === undefined ? '' : ` yoy=${formatNumber(stats.yoy, 1)}%`) +
+        (stats.zScoreLatestChange === undefined ? '' : ` z=${formatNumber(stats.zScoreLatestChange, 1)}`) +
+        (stats.percentile === undefined ? '' : ` pctile=${formatNumber(stats.percentile, 2)}`),
+    )
+    lines.push(
+      `  range: mean=${formatNumber(stats.mean, decimals)} min=${formatNumber(stats.min, decimals)}` +
+        ` max=${formatNumber(stats.max, decimals)} stdDev=${formatNumber(stats.stdDev, decimals)}` +
+        ` points=${stats.count ?? points.length} missing=${stats.missingCount ?? 0}`,
+    )
+  } else {
+    lines.push('  stats: unavailable (数据不足)')
+  }
+  // No ranking score here: it orders the internal list and is not a panel
+  // measurement, so publishing it invited the model to quote an opaque number
+  // ("attentionScore=271.5") as if it were a reading. Ordering happens in
+  // `buildDigest` and does not need to appear in the text.
+  if (Array.isArray(points) && points.length > 0) {
+    const sampled = downsample(points, DIGEST_POINTS)
+    lines.push(`  points: ${sampled.map((point) => `${point.t}:${formatNumber(point.v, decimals)}`).join(' ')}`)
+  }
+  if (sourceRef?.url) lines.push(`  source=${sourceRef.url}`)
+  return lines.join('\n')
+}
+
+/**
+ * Build the whole digest.
+ *
+ * @param {Array<object>} entries - entries for {@link indicatorBlock}.
+ * @param {{ budget?: number, title?: string, range?: { from: string, to: string }, extra?: string }} [options] - digest options.
+ * @returns {{ text: string, chars: number, included: string[], omitted: string[], truncated: boolean }} digest.
+ */
+export function buildDigest(entries, { budget = DIGEST_BUDGET, title = '可关注指标', range, extra } = {}) {
+  const guaranteed = []
+  const rest = []
+  for (const entry of entries) {
+    if ((entry.indicator?.importance ?? 0) >= 5) guaranteed.push(entry)
+    else rest.push(entry)
+  }
+  rest.sort(
+    (a, b) =>
+      (b.score ?? 0) - (a.score ?? 0) ||
+      (b.indicator?.importance ?? 0) - (a.indicator?.importance ?? 0) ||
+      String(a.indicator?.id ?? '').localeCompare(String(b.indicator?.id ?? '')),
+  )
+  const ordered = [...guaranteed, ...rest]
+
+  const header = []
+  header.push(`## ${title}`)
+  if (range !== undefined) header.push(`区间: ${range.from} .. ${range.to}`)
+  header.push(`指标数: ${entries.length}`)
+  if (extra) header.push(extra)
+
+  const blocks = ordered.map((entry) => indicatorBlock(entry))
+  const included = []
+  const omitted = []
+  let text = header.join('\n')
+
+  for (let i = 0; i < blocks.length; i += 1) {
+    const entry = ordered[i]
+    // Reserve room for the trailing omission note so a truncation is always
+    // visible to the model (docs/06 §2.3 rule 2). The reserve is charged on
+    // every block, including the last: the note is appended after the loop, and
+    // a loop that only ever skips the final block would still need the room.
+    const reserve = 240
+    if (text.length + blocks[i].length + reserve + 1 > budget) {
+      omitted.push(entry.indicator.id)
+      continue
+    }
+    text += `\n${blocks[i]}`
+    included.push(entry.indicator.id)
+  }
+
+  if (omitted.length > 0) {
+    text += `\n（已省略 ${omitted.length} 个次要指标：${omitted.slice(0, 12).join(', ')}${omitted.length > 12 ? ' …' : ''}）`
+  }
+  return { text, chars: text.length, included, omitted, truncated: omitted.length > 0 }
+}
+
+/**
+ * One line per indicator: what the panel *holds*, without the point series.
+ *
+ * A discussion session seeded with only its subject's block concluded that the
+ * panel had nothing else and told the reader so — "面板里也没有核心 CPI、CPI 环比"
+ * — while both indicators were sitting in the catalog the whole time. A detailed
+ * block answers "what do these numbers say"; this inventory answers "what else is
+ * here", which is what a session needs before it decides an answer is impossible.
+ *
+ * @param {Array<object>} entries - digest entries (`{ indicator, stats, status }`).
+ * @param {{ title?: string, skip?: string[] }} [options] - options.
+ * @returns {string} compact inventory, or '' when there is nothing to list.
+ */
+export function buildInventory(entries, { title = '面板指标清单（未展开明细，可用 data_series 取完整序列）', skip = [] } = {}) {
+  const missing = new Set(skip)
+  const listed = (entries ?? []).filter((entry) => entry?.indicator !== undefined && missing.has(entry.indicator.id) === false)
+  if (listed.length === 0) return ''
+  const lines = [`## ${title}`]
+  for (const entry of listed) {
+    const { indicator, stats } = entry
+    const decimals = indicator.display?.decimals ?? 2
+    const suffix = transformSuffix(indicator.display)
+    const parts = [`- ${indicator.id}`, indicator.label.zh, `${indicator.unit}${suffix}`, indicator.freq]
+    if (stats?.latest !== undefined && stats.latest !== null) {
+      parts.push(`latest=${formatNumber(stats.latest, decimals)}`)
+      if (typeof stats.latestAt === 'string') parts.push(`@${stats.latestAt}`)
+    } else {
+      parts.push('latest=n/a')
+    }
+    if (stats?.changeAbs !== undefined) parts.push(`Δ=${formatNumber(stats.changeAbs, decimals)}`)
+    if (stats?.changePct !== undefined) parts.push(`Δ%=${formatNumber(stats.changePct, 1)}`)
+    parts.push(`status=${entry.status ?? 'unknown'}`)
+    lines.push(parts.join(' | '))
+  }
+  return lines.join('\n')
+}
+
+/**
+ * A compact digest for the deterministic (no-LLM) summary path: the same data,
+ * rendered as readable Chinese prose rather than a table.
+ *
+ * @param {Array<object>} entries - digest entries.
+ * @param {{ today?: string, range?: { from: string, to: string } }} [options] - options.
+ * @returns {string} markdown text.
+ */
+export function renderDeterministicSummary(entries, { today, range } = {}) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return '数据不足：当前没有任何可用的指标观测，无法生成摘要。请先检查数据源可用性或缩小时间范围。'
+  }
+  const lines = []
+  lines.push(`### 时段数据摘要${range === undefined ? '' : `（${range.from} 至 ${range.to}）`}`)
+  lines.push('')
+  lines.push('**关键变化**')
+  const withChange = entries
+    .filter((entry) => entry.stats?.changeAbs !== undefined)
+    .sort((a, b) => Math.abs(b.stats.changeAbs) - Math.abs(a.stats.changeAbs) || b.indicator.importance - a.indicator.importance)
+    .slice(0, 5)
+  for (const entry of withChange) {
+    const decimals = entry.indicator.display?.decimals ?? 2
+    lines.push(
+      `- ${entry.indicator.label.zh}：${formatNumber(entry.stats.latest, decimals)}${entry.indicator.unit}` +
+        `（较上期 ${entry.stats.changeAbs >= 0 ? '+' : ''}${formatNumber(entry.stats.changeAbs, decimals)}，${entry.stats.latestAt}）`,
+    )
+  }
+  lines.push('')
+  lines.push('**值得留意的指标**')
+  const ranked = [...entries].sort((a, b) => (b.score ?? 0) - (a.score ?? 0)).slice(0, 5)
+  for (const entry of ranked) {
+    lines.push(`- ${entry.indicator.label.zh}（importance=${entry.indicator.importance}，关注分 ${entry.score ?? 0}）`)
+  }
+  lines.push('')
+  lines.push('**数据边界**')
+  const stale = entries.filter((entry) => entry.status !== 'fresh')
+  lines.push(
+    stale.length === 0
+      ? '- 本次全部指标均为最新观测。'
+      : `- 其中 ${stale.length} 个指标为陈旧或缺失状态（${stale.slice(0, 5).map((entry) => entry.indicator.label.zh).join('、')}），结论需谨慎。`,
+  )
+  if (today) lines.push(`- 生成时间：${today}（确定性摘要，未使用模型）。`)
+  lines.push('- 数据来自公开源，仅供研究参考，不构成投资建议；口径以原始来源为准。')
+  return lines.join('\n')
+}

package/src/core/insight/rank.js

@@ -0,0 +1,115 @@
+/**
+ * Merge rule hits into per-indicator scores and order the noteworthy list
+ * (docs/07 T5.2).
+ *
+ * The formula is fixed and lives here so it is reviewable:
+ *
+ *   score = Σ(hit.score × hit.weight) × importanceFactor(importance)
+ *
+ * Ties break by 'importance' descending, then 'latestAt' descending, then id —
+ * a total order, so the panel never reshuffles between two identical renders.
+ *
+ * @module core/insight/rank
+ */
+
+/** How much a catalog importance multiplies the raw rule score. */
+export const IMPORTANCE_FACTOR = { 1: 0.6, 2: 0.8, 3: 1.0, 4: 1.25, 5: 1.5 }
+
+/**
+ * Scale one indicator's raw rule score by its importance.
+ *
+ * @param {number} rawScore - sum of hit.score × hit.weight.
+ * @param {number} importance - catalog importance (1–5).
+ * @returns {number} final score, rounded to one decimal.
+ */
+export function importanceFactor(rawScore, importance) {
+  const factor = IMPORTANCE_FACTOR[importance] ?? 1
+  return Math.round(rawScore * factor * 10) / 10
+}
+
+/**
+ * Group hits by indicator and score them.
+ *
+ * @param {Array<object>} hits - hits from {@link module:core/insight/rules.runRules}.
+ * @param {{ catalogById?: Record<string, object>, statusById?: Record<string, string> }} [options] - context.
+ * @returns {Array<{ indicatorId: string, hits: object[], rawScore: number, score: number, importance: number, latestAt?: string, status?: string }>} scored entries.
+ */
+export function scoreHits(hits, { catalogById = {}, statusById = {} } = {}) {
+  const byIndicator = new Map()
+  for (const entry of hits) {
+    if (entry === null || typeof entry !== 'object') continue
+    const key = entry.indicatorId
+    if (typeof key !== 'string') continue
+    const bucket = byIndicator.get(key) ?? []
+    bucket.push(entry)
+    byIndicator.set(key, bucket)
+  }
+
+  return [...byIndicator.entries()].map(([indicatorId, bucket]) => {
+    const def = catalogById[indicatorId]
+    const importance = def?.importance ?? 1
+    const rawScore = bucket.reduce((acc, entry) => acc + (entry.score ?? 0) * (entry.weight ?? 1), 0)
+    const dates = bucket
+      .flatMap((entry) => entry.evidence?.dates ?? [])
+      .filter((date) => typeof date === 'string')
+      .sort()
+    return {
+      indicatorId,
+      hits: [...bucket].sort((a, b) => (b.score ?? 0) - (a.score ?? 0) || a.ruleId.localeCompare(b.ruleId)),
+      rawScore: Math.round(rawScore * 10) / 10,
+      score: importanceFactor(rawScore, importance),
+      importance,
+      latestAt: dates.length > 0 ? dates[dates.length - 1] : undefined,
+      status: statusById[indicatorId],
+    }
+  })
+}
+
+/**
+ * Order scored entries: highest score first, ties by importance then recency.
+ *
+ * @param {Array<object>} scored - entries from {@link scoreHits}.
+ * @param {{ limit?: number, minScore?: number }} [options] - ranking options.
+ * @returns {Array<object>} ordered entries.
+ */
+export function rankNoteworthy(scored, { limit, minScore = 0 } = {}) {
+  const filtered = scored.filter((entry) => entry.score >= minScore)
+  const ordered = [...filtered].sort(
+    (a, b) =>
+      b.score - a.score ||
+      b.importance - a.importance ||
+      String(b.latestAt ?? '').localeCompare(String(a.latestAt ?? '')) ||
+      a.indicatorId.localeCompare(b.indicatorId),
+  )
+  return limit === undefined ? ordered : ordered.slice(0, limit)
+}
+
+/**
+ * Score and order in one step — the entry point the app layer uses.
+ *
+ * @param {Array<object>} hits - rule hits.
+ * @param {{ catalogById?: Record<string, object>, statusById?: Record<string, string>, limit?: number, minScore?: number, exclude?: string[] }} [options] - options.
+ * @returns {Array<object>} ranked noteworthy entries.
+ */
+export function buildNoteworthy(hits, { catalogById = {}, statusById = {}, limit, minScore = 0, exclude = [] } = {}) {
+  const scored = scoreHits(hits, { catalogById, statusById }).filter((entry) => !exclude.includes(entry.indicatorId))
+  return rankNoteworthy(scored, { limit, minScore })
+}
+
+/**
+ * A stable short fingerprint of an input, used for AI result caching
+ * (docs/06 §6). FNV-1a: deterministic, dependency-free, and never used for
+ * security.
+ *
+ * @param {string} text - input text.
+ * @returns {string} 8-hex-character fingerprint.
+ */
+export function fingerprint(text) {
+  let hash = 0x811c9dc5
+  const source = String(text ?? '')
+  for (let i = 0; i < source.length; i += 1) {
+    hash ^= source.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193) >>> 0
+  }
+  return hash.toString(16).padStart(8, '0')
+}

package/src/core/insight/related.js

@@ -0,0 +1,90 @@
+/**
+ * Which indicators a discussion about one indicator should also see.
+ *
+ * A session seeded with a single block answers "why did CPI do this" by saying
+ * the panel has nothing else — and it is wrong: 核心 CPI 同比 and CPI 指数 are
+ * right there in the same group. The digest cannot carry the whole panel's point
+ * series, so it carries the subject's detail plus the *peers* that share a
+ * meaningful token in their id, and the caller appends a one-line inventory of
+ * everything else.
+ *
+ * Token overlap is deliberate rather than clever: `us.core.cpi.yoy` has to match
+ * `us.cpi.yoy`, which no prefix rule can do, and `us.payrolls.*` has to gather its
+ * own family. Country and shape tokens (`us`, `yoy`, `index`, `rate` …) carry no
+ * subject and are dropped, so they never pair `cn.cpi.yoy` with `us.cpi.yoy` — the
+ * group filter would reject that anyway, but an id-level rule that only works
+ * because of a second filter is a rule waiting to misfire.
+ *
+ * @module core/insight/related
+ */
+
+/** Tokens that name a *shape* of the series, not its subject. */
+export const GENERIC_TOKENS = new Set([
+  'yoy', 'mom', 'qoq', 'yy', 'change', 'level', 'index', 'idx', 'avg', 'average',
+  'rate', 'daily', 'weekly', 'monthly', 'quarterly', 'annual', 'total', 'value',
+  'us', 'cn', 'global', 'eu', 'jp', 'wb', 'pct', 'diff', 'spread', 'ratio',
+])
+
+/** How many peers a discussion context carries in full detail. */
+export const RELATED_LIMIT = 6
+
+/**
+ * Split an indicator id into its meaningful tokens.
+ *
+ * @param {string} id - indicator id, e.g. `us.core.cpi.yoy`.
+ * @returns {string[]} tokens, e.g. `['core', 'cpi']`.
+ */
+export function subjectTokens(id) {
+  if (typeof id !== 'string') return []
+  return id
+    .toLowerCase()
+    .split('.')
+    .map((token) => token.replace(/[^a-z0-9]/g, ''))
+    .filter((token) => token !== '' && GENERIC_TOKENS.has(token) === false)
+}
+
+/**
+ * The comparable form of a subject token: digits and trailing unit letters name
+ * the *instance* (`dgs10`, `dgs2`, `dgs3m`, `m1`, `m2`), not the subject, so a
+ * yield-curve or money-supply discussion has to see its own family. Taking the
+ * leading alphabetic run makes `dgs10`, `dgs2` and `dgs3m` all `dgs`, and keeps
+ * `cpi`, `pmi`, `houseprice` exact.
+ *
+ * @param {string} token - subject token.
+ * @returns {string} comparable key.
+ */
+export function subjectKey(token) {
+  const alpha = /^[a-z]+/.exec(token)
+  return alpha === null ? token : alpha[0]
+}
+
+/**
+ * Indicators that share a subject token with `indicatorId`.
+ *
+ * Same group only: a US indicator's peers are the other US indicators of the same
+ * subject, so the session reads one country's panel rather than a mixed list.
+ * Ordering prefers higher importance, then the id, so the selection is stable
+ * across calls and testable.
+ *
+ * @param {Array<{ id: string, group?: string, importance?: number }>} catalog - indicator definitions.
+ * @param {string} indicatorId - the subject.
+ * @param {{ limit?: number }} [options] - options.
+ * @returns {Array<object>} peer definitions (never includes the subject).
+ */
+export function relatedIndicators(catalog, indicatorId, { limit = RELATED_LIMIT } = {}) {
+  const entries = Array.isArray(catalog) ? catalog : []
+  const subject = entries.find((entry) => entry?.id === indicatorId)
+  if (subject === undefined) return []
+  const keys = new Set(subjectTokens(indicatorId).map(subjectKey).filter((key) => key !== ''))
+  if (keys.size === 0) return []
+  return entries
+    .filter((entry) => entry?.id !== undefined && entry.id !== indicatorId)
+    .filter((entry) => entry.group === subject.group)
+    .filter((entry) => subjectTokens(entry.id).some((token) => keys.has(subjectKey(token))))
+    .sort(
+      (a, b) =>
+        (b.importance ?? 0) - (a.importance ?? 0) ||
+        String(a.id).localeCompare(String(b.id)),
+    )
+    .slice(0, limit)
+}