dsh-plugin-show-me-data 0.1.0

package/docs/15-publish.md

@@ -0,0 +1,185 @@
+# 15 · 打包与发布（npm / GitHub）
+
+本文回答两件事：**这个插件能不能打包发布、能不能推到远程 GitHub 仓库**，以及把当前状态、还差的步骤和
+所有需要你自己决定/授权的项一次列清。相关背景见 `09-packaging-install.md`（本机安装与挂载）。
+
+结论先说：
+
+| 问题 | 答案 | 依据 |
+| --- | --- | --- |
+| 能打成 npm 包吗？ | **能**。`npm pack` 产出 337 KB / 127 文件（解包 1.5 MB），**不含** 8.3 MB 的测试 fixtures | `npm pack --dry-run` |
+| 打出来的包装得上、跑得起来吗？ | **能**。把 tarball 解到 profile 的 `node_modules` 里（**不是**软链回源码树）后真实启动：11 个源、60 个指标、8 个工具、前端半被 boot 页面引用 | `RUN_BOOT=1 node --test test/net/boot.test.js` → `the packed tarball boots a profile without the source tree` ✅ |
+| 能推到 GitHub 吗？ | **能**，仓库已经在本地初始化并 `git add` 完毕（284 文件）。推送需要**你的**远端与凭据 | 见 §3 |
+| 能直接 `npm publish` 吗？ | **还不能**，需要你先定两件事：**包名**、**LICENSE 署名**（`private: true` 也要去掉） | 见 §2 |
+
+> 本机现状：没有 `gh` CLI、没有 SSH key、没有 git 身份配置、`npm whoami` 未登录。所以**任何需要凭据的动作
+> 都必须由你执行**（或把 token 配好后再让我跑）。
+
+---
+
+## 1. 已经做好的（本次提交前已就绪）
+
+| 项 | 状态 |
+| --- | --- |
+| `npm pack` 自洽 | `files` 只含 `lib`/`src`/`docs`/`cordis.patch.yml`/`README.md`/`LICENSE`；`test/`（含 8.3 MB fixtures）不入包 |
+| 发布前自动重建产物 | `prepublishOnly` = 构建 host + client 并跑全量测试（157 项测试文件 → 683 个断言级用例） |
+| 打包后的启动门禁 | `test/net/boot.test.js` 新增用例：`npm pack` → 解包 → 真启动 → 断言路由/工具/指标数/前端半 |
+| `dsh.bundle.patch` | 已声明 `./cordis.patch.yml`，这是 `dsh plugin add <包名>` 能自动挂载那一行的前提（对照 `dsh-ai-brief`、`@wilond/dsh-news`、`dsh-holdem` 的写法） |
+| `publishConfig.access: public` | scoped 包默认是 restricted，不声明就只能发私有包 |
+| 机器相关路径 | `scripts/diag-discuss.mjs`、`test/net/boot.test.js` 全部改成 `SMD_ROOT` / `SMD_PROFILE_SOURCE` / `SMD_DSH_BIN` 等环境变量，默认值只是本机习惯 |
+| 仓库卫生 | 新增 `.gitignore`（排除 `node_modules/`、`*.tgz`、一次性备份 `.backup-web-cordis.patch.yml`）；**`lib/` 故意入库**，因为加载器直接读 `main: lib/host.js`，而从 git 安装不会跑 `prepublishOnly` |
+
+---
+
+## 2. 发布前你必须决定/授权的事
+
+### 2.1 包名 —— 已定：`dsh-plugin-show-me-data`
+
+- 与已有生态的命名一致（`dsh-plugin-usage-meter`），并且保留了插件自身的 `name: 'show-me-data'`、行 id
+  `show-me-data`、前端 bundle id；
+- **不带 scope**：不需要 npm org，别人一句 `dsh plugin add dsh-plugin-show-me-data` 就能装；
+- 已查 registry：**未被占用**（404）。若日后想收进自己名下，`@hhhcbw/dsh-plugin-show-me-data` 同样可用，
+  换 scope 时记得四件套一起换：`package.json#name`、`cordis.patch.yml#name`、`scripts/build-client.mjs#CLIENT_ID`
+  （前端半的 loader id 必须与包名一致）、`package.json#publishConfig.access = public`。
+
+改名已同步完成，且**测试与脚本改为从 `package.json` 读包名**（`test/net/boot.test.js`、`scripts/diag-discuss.mjs`），
+所以以后再改名不需要满仓库找字符串。
+
+### 2.2 `private: true` —— 已去掉
+
+npm 会拒绝发布 `private: true` 的包（`This package has been marked as private`）。该字段已移除，
+现在 `npm publish` 可以直接执行（需要有权限的 npm 账号）。
+
+### 2.3 LICENSE —— 已加（MIT，署名 hhhcbw）
+
+`LICENSE` 文件已写入 `Copyright (c) 2026 hhhcbw`，并在文末补了**数据来源说明**：`test/fixtures/` 是从
+FRED / 财政部 / 东方财富 / 新浪 / 腾讯 / 世界银行 / ECB 录制的公开数据快照，版权归各上游，仅供研究测试参考。
+
+### 2.4 README 要改成"对外版"
+
+现在的 `README.md` 是**交付文档**（"本插件已实现并安装完成 2026-09-12"、写死了 `/root/show_me_data`、
+`/data/profiles/web`）。对外发布建议补/改为：安装命令、一张面板截图、支持哪些上游、已知不可用上游、
+需要哪个 harness 版本、以及"数据仅研究参考"的免责声明。设计文档 `docs/01–14` 可原样保留（它们是本项目的
+一部分，也解释了为什么这样做）。
+
+### 2.5 harness 兼容性
+
+插件**不依赖任何 npm 包**（这是刻意的，见 `src/host/tools/define-tool.js` 顶部注释：引入第二份
+`@deepseek-ai/dsh-tools` 会 fork 工具运行时的 Symbol）。它依赖的是宿主服务：
+
+```
+inject: ['webServer', 'tools']
+可选：llm · agentDefaultModel · agentPresets · agents · sessions · timer
+```
+
+所以 README 里应写明"需要提供上述服务的 DSH 版本"（本机验证于 `dsh` 0.1.0-rc.6 一类的宿主）。
+`dsh.client.inject` 只声明 `@deepseek-ai/dsh-client-runtime`（与已发布插件一致）。
+
+---
+
+## 3. 具体命令
+
+### 3.1 推到 GitHub
+
+仓库已经是 git 仓库并已 `git add`（**未提交**，因为本机没有 git 身份）：
+
+```bash
+cd /root/show_me_data
+git config user.name  "<你的名字>"          # 或 --global
+git config user.email "<你的邮箱>"
+git commit -m "feat: show-me-data 插件 0.1.0（host 半 + 浏览器半 + 683 用例）"
+
+# 方式一：HTTPS（需要 PAT）
+git remote add origin https://github.com/<你>/<repo>.git
+git push -u origin main
+
+# 方式二：SSH（需要先把公钥加到 GitHub）
+git remote add origin git@github.com:<你>/<repo>.git
+git push -u origin main
+```
+
+`main` 分支名：本机 `git init` 的默认分支取决于 git 版本，先 `git branch -M main` 再推更稳。
+
+### 3.1b 本机推不上去时：用 GitHub API 推（本容器实测必需）
+
+本容器里 **`github.com:443` 不可达，而 `api.github.com` 可达**（同一时刻实测：`api.github.com/zen` 200，
+`github.com` 与 `codeload.github.com` 超时），所以 `git push` 必然失败（报 `Failed to connect to github.com:443`）。
+另外全局 git 配置里有 `url.git@github.com:.insteadOf=https://github.com/`，而本容器**没有 `ssh` 可执行文件**，
+因此连 HTTPS 地址也会被改写成 SSH 再失败（`cannot run ssh`）。
+
+绕开办法是走 **Git Data API**（blobs → tree → commit → ref），已封装成脚本：
+
+```bash
+GH_TOKEN=<token> node scripts/push-via-api.mjs --repo hhhcbw/dsh-plugin-show-me-data --branch main
+GH_TOKEN=<token> node scripts/push-via-api.mjs --repo hhhcbw/dsh-plugin-show-me-data --dry-run
+```
+
+脚本刻意做成"不会悄悄推错内容"：
+
+- 文件内容取自 **git 对象库**（`git cat-file blob`），不是工作区，所以未提交的改动不可能混进推送；
+- 每个 blob 上传后返回的 sha 必须与本地一致，**不一致即中止**；
+- 上传完的 **tree sha 必须等于本地 tree sha**（实测 `3991ad35…` 相同）——这才是"发布内容与本地提交逐字节一致"的真正保证；
+- 首次发布时，空仓库不允许创建 blob（`409 Git Repository is empty`），脚本会先用 Contents API 提交一份**本仓库自己的 README** 作为种子提交，然后**把分支强制指向本地那个根提交**（sha 与本地完全相同，`d7c9e6f…`），种子提交随即被丢弃；之后再推送都是 fast-forward（`force: false`），不是快进就直接报错而不是改写历史；
+- 已经推过的提交会先比对远端 tip，**幂等**（"already at this commit — nothing to do"）。
+
+验证（推完自己查）：
+
+```bash
+node -e 'fetch("https://api.github.com/repos/hhhcbw/dsh-plugin-show-me-data/git/ref/heads/main",{headers:{authorization:"Bearer $GH_TOKEN"}}).then(r=>r.json()).then(j=>console.log(j.object.sha))'
+git rev-parse HEAD          # 两个 sha 应完全相同
+```
+
+等某天 `github.com` 通了，也可以直接用 `git fetch && git reset --hard origin/main` 把本地对齐（内容零差异）。
+
+### 3.2 发布到 npm
+
+```bash
+cd /root/show_me_data
+# 1) 改包名（§2.1）+ 删掉 "private": true（§2.2）+ 加 LICENSE 署名（§2.3）
+# 2) 同步 cordis.patch.yml 与测试里的包名
+# 3) 预览要发布的内容（不会真的发布）
+npm pack --dry-run
+# 4) 登录并发布
+npm login                 # 需要浏览器/OTP
+npm publish               # prepublishOnly 会自动重建 lib/ 并跑全量测试
+```
+
+发布后任何人都可以：
+
+```bash
+dsh plugin --profile web add dsh-plugin-show-me-data   # 或 @scope/dsh-plugin-show-me-data
+```
+
+装完要**重启 web profile 进程**（插件在启动时加载），浏览器再硬刷新一次。
+
+### 3.3 只想发 GitHub、不想发 npm
+
+完全可以：把 `private` 留着，别人用
+
+```bash
+dsh plugin --profile web add github:<你>/<repo>
+```
+
+从 git 安装时 npm 会跑 `prepare`（本仓库没写 `prepare`），所以**`lib/` 必须已提交**——`.gitignore` 里已经
+特意保留了它，改 `src/` 后记得 `npm run build` 再一起提交。
+
+---
+
+## 4. 发布前的自检清单
+
+```bash
+cd /root/show_me_data
+npm run build                                  # 重新生成 lib/（改过 src 必须做）
+node --test "test/**/*.test.js"                # 683 通过 / 0 失败
+RUN_BOOT=1 node --test test/net/boot.test.js   # 4 通过：含"打包后能真启动"
+npm pack --dry-run                             # 看清单与体积
+git status --short                             # 确认没有把 .tgz / 备份文件 / node_modules 提交进去
+```
+
+## 5. 已知边界（写进 README 更诚实）
+
+- **数据上游会封 IP**：BLS(403)、Yahoo(403)、Stooq(JS 墙)、新浪 hq(403)、`data.stats.gov.cn`(403)、
+  东财 `push2his` 偶发断连。面板对每个源分类报错并降级，不猜接口（见 `docs/04-sources.md`）。
+- **面板只读**：运行时无法注册新数据源；「我的」里加不了时会开一个**迭代会话**去改插件代码。
+- **AI 是可选能力**：没有 `llm` 服务时全部走确定性摘要（这是产品特性，不是故障）。
+- **讨论会话会真开会话**：每次点「讨论」新建一个 DSH 会话并把面板数据作为上下文，不消耗面板自己的进程。

package/lib/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')
+}