dsh-plugin-show-me-data 0.1.0

package/lib/host/tools/register.js

@@ -0,0 +1,431 @@
+/**
+ * The eight model tools (docs/06 §5).
+ *
+ * The tools are the conversational entry point into the same use cases the panel
+ * calls, so "ask the agent to add an indicator" needs no extra plumbing. Each one
+ * declares a JSON Schema for its arguments and for its canonical output; the
+ * definition builder validates both.
+ *
+ * @module host/tools/register
+ */
+import { defineTool, summarize } from './define-tool.js'
+import { adapterIds, listCapabilities } from '../../sources/registry.js'
+
+/** Tool names, in the order they are registered. */
+export const TOOL_NAMES = [
+  'data_overview',
+  'data_series',
+  'data_search',
+  'data_watchlist',
+  'data_explain',
+  'data_digest',
+  'data_refresh',
+  'data_health',
+]
+
+/** Throttle window for 'data_refresh' (docs/06 §5). */
+export const REFRESH_THROTTLE_MS = 60_000
+
+/**
+ * Create the tool definitions.
+ *
+ * @param {object} deps - dependencies.
+ * @param {object} deps.useCases - '{ overview, seriesView, watchlist, health, ai, search }'.
+ * @param {import('../ports/clock.js').Clock} deps.clock - clock.
+ * @param {(msg: string, meta?: object) => void} [deps.log] - logger.
+ * @returns {object[]} tool definitions.
+ */
+export function createToolDefinitions({ useCases, clock, log = () => {} }) {
+  /** @type {number} */
+  let lastRefreshAt = 0
+
+  /**
+   * Project a metric card down to what a model needs.
+   *
+   * @param {object} metric - card.
+   * @returns {object} slim metric.
+   */
+  const slimMetric = (metric) => ({
+    indicatorId: metric.indicatorId,
+    group: metric.group,
+    label: metric.label,
+    unit: metric.unit,
+    status: metric.status,
+    latest: metric.latest,
+    latestAt: metric.latestAt,
+    changeAbs: metric.changeAbs,
+    changePct: metric.changePct,
+    yoy: metric.yoy,
+    score: metric.score,
+    sourceRef: metric.sourceRef,
+  })
+
+  const rangeParam = { type: 'string', description: 'Range preset: 1M, 3M, 6M, YTD, 1Y, 3Y, 5Y, MAX.' }
+
+  return [
+    defineTool({
+      name: 'data_overview',
+      description:
+        'Global indicator radar: today\'s most noteworthy macro/rates/equity/bond indicators plus all core cards. Use it to answer "what is worth watching today".',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          range: rangeParam,
+          groups: { type: 'array', items: { type: 'string', enum: ['US', 'CN', 'GLOBAL', 'CUSTOM'] }, description: 'Restrict to these groups.' },
+          limit: { type: 'integer', description: 'How many noteworthy items to return (1-20).' },
+        },
+      },
+      outputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        required: ['range', 'metrics', 'noteworthy', 'sources'],
+        properties: {
+          range: { type: 'object', additionalProperties: true },
+          metrics: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          noteworthy: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          sources: { type: 'object', additionalProperties: true },
+        },
+      },
+      render: (_args, value) => [
+        {
+          type: 'text',
+          text: [
+            `区间 ${value.range.from} .. ${value.range.to}；共 ${value.metrics.length} 个指标。`,
+            value.noteworthy.length === 0
+              ? '没有触发值得关注的规则。'
+              : `值得关注（${value.noteworthy.length}）：\n${value.noteworthy
+                  .map((item) => `- ${item.label?.zh ?? item.indicatorId}：${(item.reasons ?? []).map((reason) => reason.reason?.zh).join('；')}`)
+                  .join('\n')}`,
+            `来源状态：${Object.entries(value.sources)
+              .map(([key, status]) => `${key} ok=${status.ok} stale=${status.degraded} failed=${status.failed}`)
+              .join(' | ')}`,
+          ].join('\n'),
+        },
+      ],
+      execute: async (args) => {
+        const result = await useCases.overview({
+          range: args.range ?? '1Y',
+          groups: args.groups,
+          limit: args.limit,
+        })
+        return {
+          range: result.range,
+          metrics: result.metrics.map(slimMetric),
+          noteworthy: result.noteworthy,
+          sources: result.sources,
+          degraded: result.degraded,
+          generatedAt: result.generatedAt,
+        }
+      },
+    }),
+
+    defineTool({
+      name: 'data_series',
+      description:
+        'Fetch one indicator\'s detail: the point series, its statistics and its provenance. Use it before explaining a specific number.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['indicator'],
+        properties: {
+          indicator: { type: 'string', description: 'Indicator id (e.g. us.cpi.yoy) or a keyword to resolve.' },
+          range: rangeParam,
+          transform: { type: 'string', description: 'Override the display transform: raw, diff, pctChange, yoy, mom, annualize.' },
+          compareWith: { type: 'string', description: 'Second indicator id to join on dates.' },
+        },
+      },
+      outputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        required: ['indicatorId', 'points', 'status'],
+        properties: {
+          indicatorId: { type: 'string' },
+          points: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          status: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [
+        {
+          type: 'text',
+          text:
+            value.error !== undefined
+              ? `无法取数：${value.error.detail ?? value.error.code}`
+              : `${value.indicatorId} ${value.status}：最新 ${value.stats?.latest ?? 'n/a'} @${value.stats?.latestAt ?? 'n/a'}，共 ${value.points.length} 个点；来源 ${value.sourceRef?.url ?? 'n/a'}`,
+        },
+      ],
+      execute: async (args) => {
+        const resolved = await resolveIndicatorId(useCases, args.indicator)
+        if (resolved === undefined) return { indicatorId: args.indicator, points: [], status: 'error', error: { code: 'unknown-indicator', detail: `no indicator matches ${args.indicator}` } }
+        const view = await useCases.seriesView({ indicatorId: resolved, range: args.range ?? '1Y', transform: args.transform, compareWith: args.compareWith })
+        if (view?.error !== undefined) return { indicatorId: resolved, points: [], status: 'error', error: view.error, view: view.view }
+        return {
+          indicatorId: view.indicatorId,
+          label: view.label,
+          unit: view.unit,
+          range: view.range,
+          status: view.status,
+          stats: view.stats,
+          points: view.points,
+          compare: view.compare === undefined ? undefined : { indicatorId: view.compare.indicatorId, points: view.compare.points },
+          sourceRef: view.sourceRef,
+        }
+      },
+    }),
+
+    defineTool({
+      name: 'data_search',
+      description: 'Search the indicator catalog or the source list by keyword, in Chinese or English.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['q'],
+        properties: {
+          q: { type: 'string', description: 'Keyword, e.g. 非农 / CPI / 国债.' },
+          kind: { type: 'string', enum: ['indicator', 'source'], description: 'Search indicators (default) or data sources.' },
+          limit: { type: 'integer', description: 'Maximum results (1-50).' },
+        },
+      },
+      outputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['kind', 'matches'],
+        properties: {
+          kind: { type: 'string' },
+          matches: { type: 'array' },
+          suggestions: { type: 'array', items: { type: 'string' } },
+          registered: { type: 'array', items: { type: 'string' } },
+        },
+      },
+      render: (_args, value) => [
+        {
+          type: 'text',
+          text:
+            value.matches.length === 0
+              ? `没有匹配结果${value.suggestions?.length ? `；可试试：${value.suggestions.join(', ')}` : ''}`
+              : value.matches.map((entry) => `${entry.indicatorId ?? entry.id} — ${entry.label?.zh ?? entry.label}`).join('\n'),
+        },
+      ],
+      execute: async (args) => {
+        if (args.kind === 'source') {
+          const needle = String(args.q).toLowerCase()
+          const matches = listCapabilities()
+            .filter((entry) => entry.id.includes(needle) || entry.label.toLowerCase().includes(needle))
+            .map((entry) => ({ id: entry.id, label: entry.label, capabilities: entry.capabilities }))
+          return { kind: 'source', matches: matches.slice(0, args.limit ?? 12), registered: adapterIds() }
+        }
+        const result = await useCases.search(args.q, { limit: args.limit })
+        return { kind: 'indicator', matches: result.matches, suggestions: result.suggestions }
+      },
+    }),
+
+    defineTool({
+      name: 'data_watchlist',
+      description: 'Read or change the user\'s watchlist: list, add, remove, update or reorder custom indicators. `add` is idempotent.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['action'],
+        properties: {
+          action: { type: 'string', enum: ['list', 'add', 'remove', 'update', 'reorder'] },
+          indicatorId: { type: 'string', description: 'Target indicator id (add/remove/update).' },
+          item: { type: 'object', additionalProperties: true, description: 'Item to add: { indicatorId, definition?, createdBy? }.' },
+          patch: { type: 'object', additionalProperties: true, description: 'Fields to change (update).' },
+          ids: { type: 'array', items: { type: 'string' }, description: 'Desired order (reorder).' },
+        },
+      },
+      outputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        required: ['status', 'items'],
+        properties: {
+          status: { type: 'string' },
+          items: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        },
+      },
+      render: (_args, value) => [
+        {
+          type: 'text',
+          text:
+            `清单（${value.items.length}）：` +
+            (value.items.length === 0 ? '（空）' : value.items.map((item) => item.indicatorId).join(', ')) +
+            (value.status === 'exists' ? '\n（该项已存在，未重复添加）' : ''),
+        },
+      ],
+      execute: async (args) => {
+        if (args.action === 'list') return { status: 'listed', items: await useCases.watchlist.list() }
+        if (args.action === 'add') {
+          const result = await useCases.watchlist.add(args.item ?? { indicatorId: args.indicatorId }, { createdBy: 'ai' })
+          if (result.error !== undefined) return { status: 'invalid', items: await useCases.watchlist.list(), error: result.error }
+          return { status: result.created ? 'created' : 'exists', item: result.item, conflict: result.conflict === true, items: await useCases.watchlist.list() }
+        }
+        if (args.action === 'remove') {
+          const result = await useCases.watchlist.remove(args.indicatorId)
+          return { status: result.status, items: await useCases.watchlist.list() }
+        }
+        if (args.action === 'update') {
+          const result = await useCases.watchlist.update(args.indicatorId, args.patch ?? {})
+          return { status: result.status, item: result.item, items: await useCases.watchlist.list() }
+        }
+        if (args.action === 'reorder') {
+          const result = await useCases.watchlist.reorder(args.ids ?? [])
+          return { status: 'reordered', items: result.items, missing: result.missing }
+        }
+        return { status: 'unknown-action', items: await useCases.watchlist.list() }
+      },
+    }),
+
+    defineTool({
+      name: 'data_explain',
+      description: 'Explain one indicator using only panel data: what it is, what the latest reading means, history, possible implications and reverse risks.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['indicator'],
+        properties: {
+          indicator: { type: 'string', description: 'Indicator id or keyword.' },
+          range: rangeParam,
+        },
+      },
+      outputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        required: ['markdown', 'mode'],
+        properties: {
+          markdown: { type: 'string' },
+          mode: { type: 'string' },
+          usedPoints: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        },
+      },
+      render: (_args, value) => [{ type: 'text', text: `${value.markdown}${value.usedPoints?.length ? `\n\n引用了 ${value.usedPoints.length} 个数据点（mode=${value.mode}）。` : ''}` }],
+      execute: async (args) => {
+        const resolved = await resolveIndicatorId(useCases, args.indicator)
+        const result = await useCases.ai.explain({ indicatorId: resolved ?? args.indicator, range: args.range ?? '1Y' })
+        return result
+      },
+    }),
+
+    defineTool({
+      name: 'data_digest',
+      description: 'Produce a period summary across the panel: key changes, corroboration, contradictions and what to watch next.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          range: rangeParam,
+          indicators: { type: 'array', items: { type: 'string' }, description: 'Restrict the digest to these indicator ids.' },
+        },
+      },
+      outputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        required: ['markdown', 'mode'],
+        properties: { markdown: { type: 'string' }, mode: { type: 'string' } },
+      },
+      render: (_args, value) => [{ type: 'text', text: value.markdown }],
+      execute: async (args) => useCases.ai.summarize({ range: args.range ?? '1Y', indicators: args.indicators }),
+    }),
+
+    defineTool({
+      name: 'data_refresh',
+      description: 'Force a cache refresh for one indicator (or all visible ones). Throttled to once per minute.',
+      parameters: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          indicator: { type: 'string', description: 'Indicator id; omit to refresh the default overview set.' },
+        },
+      },
+      outputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        required: ['status'],
+        properties: { status: { type: 'string' }, throttled: { type: 'boolean' } },
+      },
+      render: (_args, value) => [
+        {
+          type: 'text',
+          text: value.throttled
+            ? `距上次刷新不足 ${REFRESH_THROTTLE_MS / 1000} 秒，已跳过（数据仍是最新的缓存）。`
+            : `已刷新：${value.refreshed ?? 0} 项，失败 ${value.failed ?? 0} 项。`,
+        },
+      ],
+      execute: async (args) => {
+        const now = clock.now().getTime()
+        if (now - lastRefreshAt < REFRESH_THROTTLE_MS) {
+          log('data_refresh throttled', { sinceMs: now - lastRefreshAt })
+          return { status: 'throttled', throttled: true, sinceMs: now - lastRefreshAt }
+        }
+        lastRefreshAt = now
+        const ids = args.indicator === undefined ? undefined : [args.indicator]
+        const result = await useCases.overview({ range: '1Y', ids, force: true, limit: 1 })
+        return {
+          status: 'refreshed',
+          throttled: false,
+          refreshed: result.metrics.filter((metric) => metric.status === 'fresh').length,
+          failed: result.metrics.filter((metric) => metric.status === 'error').length,
+          range: result.range,
+        }
+      },
+    }),
+
+    defineTool({
+      name: 'data_health',
+      description: 'Report per-source availability and the last successful fetch time. Use it to diagnose "why is there no data today".',
+      parameters: { type: 'object', additionalProperties: false, properties: {} },
+      outputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        required: ['sources'],
+        properties: {
+          sources: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        },
+      },
+      render: (_args, value) => [
+        {
+          type: 'text',
+          text: value.sources.map((entry) => `${entry.adapterId}: ${entry.available ? 'ok' : 'failed'}${entry.lastSuccessAt ? ` (last success ${entry.lastSuccessAt})` : ''}`).join('\n'),
+        },
+      ],
+      execute: async () => {
+        const health = await useCases.health({ probe: false })
+        return { sources: health.sources, generatedAt: health.generatedAt, aiMode: health.aiMode }
+      },
+    }),
+  ]
+}
+
+/**
+ * Resolve a user-supplied indicator reference to a catalog id.
+ *
+ * @param {object} useCases - use cases.
+ * @param {string} reference - id or keyword.
+ * @returns {Promise<string|undefined>} resolved id.
+ */
+async function resolveIndicatorId(useCases, reference) {
+  if (typeof reference !== 'string' || reference.trim() === '') return undefined
+  const result = await useCases.search(reference, { limit: 3 })
+  const exact = result.matches.find((entry) => entry.id === reference)
+  if (exact !== undefined) return exact.id
+  return result.matches[0]?.id
+}
+
+/**
+ * Register every tool, returning one disposer for the whole set.
+ *
+ * @param {object} deps - dependencies.
+ * @param {{ register: (definition: object) => () => void }} deps.tools - tool registry.
+ * @param {object} deps.useCases - use cases.
+ * @param {import('../ports/clock.js').Clock} deps.clock - clock.
+ * @param {(msg: string, meta?: object) => void} [deps.log] - logger.
+ * @returns {() => void} disposer.
+ */
+export function registerTools({ tools, useCases, clock, log = () => {} }) {
+  const disposers = createToolDefinitions({ useCases, clock, log }).map((definition) => tools.register(definition))
+  return () => {
+    for (const dispose of disposers.reverse()) dispose()
+  }
+}
+
+/** Re-exported so the tool definitions can be inspected in tests. */
+export { summarize }

package/lib/host.js

@@ -0,0 +1,7 @@
+// GENERATED FILE — do not edit. Source: src/host/index.js
+// Rebuild with: node scripts/build-host.mjs
+//
+// `lib/` mirrors `src/` so the package is self-contained: the profile resolves
+// this file through package.json's `main`, and every relative import inside the
+// published tree resolves within it.
+export { name, inject, apply, Config, PLUGIN_ROOT } from './host/index.js'

package/lib/ports/clock.js

@@ -0,0 +1,57 @@
+/**
+ * Time source port (docs/02 §3.2). All date arithmetic in 'core/' and 'app/'
+ * goes through a Clock so tests are deterministic and timezone-free.
+ *
+ * @typedef {Object} Clock
+ * @property {() => Date} now - current instant.
+ * @property {() => string} today - current calendar date as 'YYYY-MM-DD'.
+ * @property {(iso: string) => string} toDateString - 'YYYY-MM-DD' of an instant.
+ */
+
+/**
+ * Format a 'Date' as a local 'YYYY-MM-DD' calendar date.
+ *
+ * @param {Date} date - instant to format.
+ * @returns {string} 'YYYY-MM-DD'.
+ */
+export function toDateString(date) {
+  const y = date.getFullYear()
+  const m = String(date.getMonth() + 1).padStart(2, '0')
+  const d = String(date.getDate()).padStart(2, '0')
+  return `${y}-${m}-${d}`
+}
+
+/**
+ * The system clock: the only place in this package allowed to read real time.
+ *
+ * @returns {Clock} system-backed clock.
+ */
+export function systemClock() {
+  return {
+    now: () => new Date(),
+    today: () => toDateString(new Date()),
+    toDateString: (iso) => toDateString(new Date(iso)),
+  }
+}
+
+/**
+ * A clock pinned to one instant. Tests use this so no assertion depends on the
+ * machine's date or timezone.
+ *
+ * @param {string} iso - pinned instant, e.g. '2026-09-12T00:00:00.000Z'.
+ * @returns {Clock & { advance: (ms: number) => void, set: (iso: string) => void }} fixed clock.
+ */
+export function fixedClock(iso) {
+  let at = new Date(iso)
+  return {
+    now: () => new Date(at.getTime()),
+    today: () => toDateString(at),
+    toDateString: (value) => toDateString(new Date(value)),
+    advance: (ms) => {
+      at = new Date(at.getTime() + ms)
+    },
+    set: (value) => {
+      at = new Date(value)
+    },
+  }
+}

package/lib/ports/snapshot-repo.js

@@ -0,0 +1,48 @@
+/**
+ * Snapshot cache port (docs/02 §3.2, §4.2). Implemented by an fs-backed
+ * repository in the host half and by an in-memory one in tests.
+ *
+ * 'read' returns '{ payload, storedAt, ttlMs }' or 'undefined'; freshness is
+ * decided by the use case with an injected Clock, never by the repository.
+ *
+ * @typedef {Object} CacheEntry
+ * @property {any} payload - cached JSON value.
+ * @property {string} storedAt - ISO timestamp written by the clock.
+ * @property {number} ttlMs - TTL that applied when the entry was written.
+ *
+ * @typedef {Object} SnapshotRepository
+ * @property {(key: string) => Promise<CacheEntry | undefined>} read
+ * @property {(key: string, payload: any, opts: { ttlMs: number, at: string }) => Promise<void>} write
+ * @property {() => Promise<Array<{ key: string, storedAt: string, ttlMs: number }>>} list
+ * @property {() => Promise<void>} clear
+ */
+
+/**
+ * @typedef {Object} WatchlistItem
+ * @property {string} indicatorId
+ * @property {string} [addedAt]
+ * @property {'user'|'ai'|'catalog'} [createdBy]
+ * @property {number} [order]
+ */
+
+/**
+ * Watchlist persistence port (docs/02 §3.2).
+ *
+ * @typedef {Object} WatchlistRepository
+ * @property {() => Promise<WatchlistItem[]>} list
+ * @property {(item: WatchlistItem) => Promise<{ item: WatchlistItem, created: boolean }>} add
+ * @property {(indicatorId: string) => Promise<'removed'|'notFound'>} remove
+ * @property {(indicatorId: string, patch: Partial<WatchlistItem>) => Promise<WatchlistItem|undefined>} update
+ */
+
+/** @type {SnapshotRepository} */
+export const noopSnapshotRepository = {
+  async read() {
+    return undefined
+  },
+  async write() {},
+  async list() {
+    return []
+  },
+  async clear() {},
+}