dsh-plugin-show-me-data 0.1.0

package/src/host/http/routes.js

@@ -0,0 +1,689 @@
+/**
+ * The HTTP route table (docs/05 §3, docs/07 T7.2).
+ *
+ * Every handler is a thin projection of a use case: parse, call, serialise. The
+ * router itself is a pure factory over the use cases, so tests call it with fake
+ * request/response objects and no server.
+ *
+ * @module host/http/routes
+ */
+import { API_PREFIX, errorPayload, intParam, listParam, parseRoute, readJsonBody, sendError, sendJson, startSse } from './respond.js'
+import { violationLines } from '../../app/ai-validate.js'
+import { buildDigest, buildInventory } from '../../core/insight/digest.js'
+import { relatedIndicators } from '../../core/insight/related.js'
+
+/**
+ * Character budget for one discussion's seeded context.
+ *
+ * The one-shot panel answers are validated against their digest, so that digest
+ * stays small; a discussion is a real session the reader keeps talking to, and a
+ * context that omits half the panel is what made a session refuse a question it
+ * could have answered.
+ */
+const DISCUSSION_BUDGET = 12000
+
+/**
+ * Translate one panel bar size into the parameter its source actually takes.
+ *
+ * Eastmoney's kline API speaks `klt` (101/102/103); Sina's speaks `scale`
+ * (minutes). A source that declares no support gets nothing, so the panel's
+ * period control can never silently return the same chart three times.
+ *
+ * @param {object} useCases - use cases.
+ * @param {string} indicatorId - indicator id.
+ * @param {string|null} freq - 'day' | 'week' | 'month' | null.
+ * @returns {object|undefined} source-param override.
+ */
+function supportsBars(useCases, indicatorId) {
+  const indicator = useCases.catalog.all.find((entry) => entry.id === indicatorId)
+  return useCases.catalog.barSizes?.(indicator?.source?.adapter) === true
+}
+
+/**
+ * @param {object} useCases - use cases.
+ * @param {string} indicatorId - indicator id.
+ * @param {string|null} freq - requested bar size.
+ * @returns {object|undefined} source-param override.
+ */
+function barParams(useCases, indicatorId, freq) {
+  if (freq === null || freq === 'day') return undefined
+  const indicator = useCases.catalog.all.find((entry) => entry.id === indicatorId)
+  const adapterId = indicator?.source?.adapter
+  if (useCases.catalog.barSizes?.(adapterId) !== true) return undefined
+  // The neutral size name: an adapter that owns several upstreams (the quote
+  // cascade) is the only one that knows which parameter its winner takes.
+  return { size: freq }
+}
+
+/** Routes the panel calls, with their methods. */
+export const ROUTES = [
+  { method: 'GET', path: '/health' },
+  { method: 'GET', path: '/settings' },
+  { method: 'GET', path: '/overview' },
+  { method: 'GET', path: '/series' },
+  { method: 'GET', path: '/watchlist' },
+  { method: 'POST', path: '/watchlist' },
+  { method: 'GET', path: '/catalog/search' },
+  { method: 'POST', path: '/ai/explain' },
+  { method: 'POST', path: '/ai/summary' },
+  { method: 'POST', path: '/ai/overview' },
+  { method: 'POST', path: '/ai/ask' },
+  { method: 'POST', path: '/ai/propose' },
+  { method: 'POST', path: '/discuss' },
+  { method: 'GET', path: '/discuss/answer' },
+  { method: 'POST', path: '/iterate' },
+]
+
+/**
+ * Create the route dispatcher.
+ *
+ * @param {object} deps - dependencies.
+ * @param {object} deps.useCases - '{ overview, seriesView, watchlist, health, ai }'.
+ * @param {(msg: string, meta?: object) => void} [deps.log] - logger.
+ * @param {(durationMs: number, meta: object) => void} [deps.metrics] - metrics sink.
+ * @returns {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => Promise<void>} handler.
+ */
+export function createRoutes({ useCases, log = () => {}, metrics = () => {} }) {
+  /**
+   * Dispatch one request.
+   *
+   * @param {import('node:http').IncomingMessage} req - request.
+   * @param {import('node:http').ServerResponse} res - response.
+   * @returns {Promise<void>} completion.
+   */
+  async function handler(req, res) {
+    const started = Date.now()
+    const { route, query } = parseRoute(req)
+    const method = (req.method ?? 'GET').toUpperCase()
+    try {
+      switch (route) {
+        case 'health':
+          return await handleHealth(res, useCases, query)
+        case 'settings':
+          return handleSettings(res, useCases)
+        case 'overview':
+          return await handleOverview(req, res, useCases, query)
+        case 'series':
+          return await handleSeries(res, useCases, query)
+        case 'watchlist':
+          return method === 'POST'
+            ? await handleWatchlistPost(req, res, useCases)
+            : await handleWatchlistGet(res, useCases)
+        case 'catalog/search':
+          return await handleSearch(res, useCases, query)
+        case 'ai/explain':
+          return await handleAiExplain(req, res, useCases)
+        case 'ai/summary':
+          return await handleAiSummary(req, res, useCases)
+        case 'ai/overview':
+          return await handleAiOverview(req, res, useCases)
+        case 'ai/ask':
+          return await handleAiAsk(req, res, useCases)
+        case 'ai/propose':
+          return await handleAiPropose(req, res, useCases)
+        case 'discuss':
+          return await handleDiscuss(req, res, useCases)
+        case 'discuss/answer':
+          return handleDiscussAnswer(res, useCases, query)
+        case 'iterate':
+          return await handleIterate(req, res, useCases)
+        default:
+          return sendError(res, 404, 'not-found', `no route ${JSON.stringify(route)} under ${API_PREFIX}`)
+      }
+    } catch (error) {
+      const payload = errorPayload(error)
+      log('route failed', { route, method, kind: payload.kind, message: error?.message ?? String(error) })
+      if (!res.headersSent) sendError(res, payload.status, payload.kind, payload.detail, { retryable: payload.retryable })
+      else res.end()
+    } finally {
+      metrics(Date.now() - started, { route, method })
+    }
+  }
+
+  return handler
+}
+
+/**
+ * '/health' — per-source availability and the resolved mode.
+ *
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @param {URLSearchParams} query - query.
+ * @returns {Promise<void>} completion.
+ */
+async function handleHealth(res, useCases, query) {
+  // `ids` narrows a probe to the indicators behind one adapter, which the
+  // settings screen uses for a per-source connection test.
+  // `listParam` answers `undefined` when the key is absent, and this route is
+  // also called by tests with no query object at all.
+  const ids = query?.get === undefined ? undefined : listParam(query, 'ids')
+  const result = await useCases.health({
+    probe: query?.get?.('probe') === '1',
+    range: query?.get?.('range') ?? undefined,
+    ids: ids === undefined || ids.length === 0 ? undefined : ids,
+  })
+  sendJson(res, 200, result)
+}
+
+/**
+ * '/settings' — the mount's effective configuration, for the settings screen.
+ *
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @returns {void} completion.
+ */
+function handleSettings(res, useCases) {
+  sendJson(res, 200, useCases.settings())
+}
+
+/**
+ * '/overview' — cards, noteworthy list and source health.
+ *
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @param {URLSearchParams} query - query.
+ * @returns {Promise<void>} completion.
+ */
+async function handleOverview(req, res, useCases, query) {
+  const range = query.get('range') ?? '1Y'
+  const groups = listParam(query, 'groups')
+  const ids = listParam(query, 'ids')
+  const request = {
+    range,
+    groups,
+    ids,
+    limit: intParam(query, 'limit', 5, { min: 1, max: 20 }),
+    force: query.get('force') === '1',
+    custom: query.has('from') || query.has('to')
+      ? { from: query.get('from'), to: query.get('to') }
+      : undefined,
+  }
+  if (request.custom !== undefined && (request.custom.from === null || request.custom.to === null)) {
+    return sendError(res, 400, 'bad-request', 'CUSTOM range needs both `from` and `to`')
+  }
+  const result = await useCases.overview(request)
+  sendJson(res, 200, result)
+}
+
+/**
+ * '/series' — one indicator's detail view.
+ *
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @param {URLSearchParams} query - query.
+ * @returns {Promise<void>} completion.
+ */
+async function handleSeries(res, useCases, query) {
+  const indicatorId = query.get('indicator')
+  if (indicatorId === null || indicatorId.trim() === '') {
+    return sendError(res, 400, 'bad-request', 'the `indicator` query parameter is required')
+  }
+  // `freq` selects the bar size for sources that publish OHLC (day/week/month);
+  // it is passed through as a source-param override, so it is part of the cache
+  // key rather than a presentation-only flag.
+  const freq = query.get('freq')
+  const view = await useCases.seriesView({
+    indicatorId,
+    range: query.get('range') ?? '1Y',
+    transform: query.get('transform') ?? undefined,
+    compareWith: query.get('compareWith') ?? undefined,
+    params: barParams(useCases, indicatorId, freq),
+    barSizes: supportsBars(useCases, indicatorId),
+  })
+  if (view?.error !== undefined) {
+    const status = view.error.code === 'unknown-indicator' ? 404 : 409
+    return sendError(res, status, view.error.code, view.error.detail)
+  }
+  sendJson(res, 200, view)
+}
+
+/**
+ * 'GET /watchlist'.
+ *
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @returns {Promise<void>} completion.
+ */
+async function handleWatchlistGet(res, useCases) {
+  sendJson(res, 200, { items: await useCases.watchlist.list() })
+}
+
+/**
+ * 'POST /watchlist' — add / remove / update / reorder.
+ *
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @returns {Promise<void>} completion.
+ */
+async function handleWatchlistPost(req, res, useCases) {
+  const body = await readJsonBody(req)
+  const action = body.action
+  if (action === 'add') {
+    const result = await useCases.watchlist.add(body.item ?? {}, { createdBy: body.createdBy ?? 'user' })
+    if (result.error !== undefined) return sendError(res, 400, result.error.code, result.error.detail)
+    return sendJson(res, result.created ? 201 : 200, { status: result.created ? 'created' : 'exists', item: result.item, conflict: result.conflict === true, items: await useCases.watchlist.list() })
+  }
+  if (action === 'remove') {
+    const result = await useCases.watchlist.remove(body.indicatorId)
+    if (result.status === 'notFound') return sendError(res, 404, 'not-found', `${body.indicatorId} is not in the watchlist`)
+    return sendJson(res, 200, { status: 'removed', items: await useCases.watchlist.list() })
+  }
+  if (action === 'update') {
+    const result = await useCases.watchlist.update(body.indicatorId, body.patch ?? {})
+    if (result.status === 'notFound') return sendError(res, 404, 'not-found', `${body.indicatorId} is not in the watchlist`)
+    return sendJson(res, 200, { status: 'updated', item: result.item, items: await useCases.watchlist.list() })
+  }
+  if (action === 'reorder') {
+    if (!Array.isArray(body.ids)) return sendError(res, 400, 'bad-request', '`ids` must be an array')
+    const result = await useCases.watchlist.reorder(body.ids)
+    return sendJson(res, 200, { status: 'reordered', items: result.items, missing: result.missing })
+  }
+  return sendError(res, 400, 'bad-request', `unknown action ${JSON.stringify(action)}`)
+}
+
+/**
+ * 'GET /catalog/search'.
+ *
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @param {URLSearchParams} query - query.
+ * @returns {Promise<void>} completion.
+ */
+async function handleSearch(res, useCases, query) {
+  const result = await useCases.search(query.get('q') ?? '', {
+    groups: listParam(query, 'groups'),
+    limit: intParam(query, 'limit', 12, { min: 1, max: 50 }),
+  })
+  sendJson(res, 200, result)
+}
+
+/**
+ * 'POST /ai/explain' and friends: run the AI use case and stream the answer.
+ *
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @returns {Promise<void>} completion.
+ */
+async function handleAiExplain(req, res, useCases) {
+  const body = await readJsonBody(req)
+  if (typeof body.indicator !== 'string') return sendError(res, 400, 'bad-request', '`indicator` is required')
+  const request = { indicatorId: body.indicator, range: body.range ?? '1Y', stream: body.stream === true }
+  await runAi(res, useCases, () => useCases.ai.explain(request), request.stream)
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @returns {Promise<void>} completion.
+ */
+async function handleAiSummary(req, res, useCases) {
+  const body = await readJsonBody(req)
+  const request = { range: body.range ?? '1Y', indicators: Array.isArray(body.indicators) ? body.indicators : undefined, stream: body.stream === true }
+  await runAi(res, useCases, () => useCases.ai.summarize(request), request.stream)
+}
+
+/**
+ * 'POST /ai/overview' — analyse the panel as a whole, or one group of it.
+ *
+ * The digest behind this carries every observable in scope *and* the triggered
+ * attention rules, so the answer is about structure ("what is going on") rather
+ * than about one series.
+ *
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @returns {Promise<void>} completion.
+ */
+async function handleAiOverview(req, res, useCases) {
+  const body = await readJsonBody(req)
+  // A JSON body carries the list natively; only a comma-joined string needs
+  // splitting, which is the form a query string would use.
+  const groups = Array.isArray(body.groups)
+    ? body.groups.filter((entry) => typeof entry === 'string' && entry !== '')
+    : typeof body.groups === 'string' && body.groups !== ''
+      ? body.groups.split(',').map((entry) => entry.trim()).filter(Boolean)
+      : []
+  const request = {
+    range: body.range ?? '1Y',
+    groups: groups.length === 0 ? undefined : groups,
+    limit: Number.isInteger(body.limit) ? body.limit : undefined,
+    stream: body.stream === true,
+  }
+  await runAi(res, useCases, () => useCases.ai.overviewAnalysis(request), request.stream)
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @returns {Promise<void>} completion.
+ */
+async function handleAiAsk(req, res, useCases) {
+  const body = await readJsonBody(req)
+  if (typeof body.question !== 'string' || body.question.trim() === '') {
+    return sendError(res, 400, 'bad-request', '`question` is required')
+  }
+  const request = { question: body.question, range: body.range ?? '1Y', stream: body.stream === true }
+  await runAi(res, useCases, () => useCases.ai.ask(request), request.stream)
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @returns {Promise<void>} completion.
+ */
+async function handleAiPropose(req, res, useCases) {
+  const body = await readJsonBody(req)
+  if (typeof body.text !== 'string' || body.text.trim() === '') {
+    return sendError(res, 400, 'bad-request', '`text` is required')
+  }
+  const result = await useCases.ai.propose({ text: body.text, verify: body.verify !== false })
+  sendJson(res, 200, result)
+}
+
+/**
+ * `POST /iterate` — open a session in the plugin workspace to extend the plugin.
+ *
+ * "不能添加，因为没有可用数据源" is the honest answer from a read-only panel, and a
+ * dead end for the reader. The plugin cannot register a source at runtime, but it
+ * can hand the request to a session that can: this opens one in the plugin root
+ * with the request, the per-indicator reasons and the extension contract attached.
+ *
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @returns {Promise<void>} completion.
+ */
+async function handleIterate(req, res, useCases) {
+  const body = await readJsonBody(req)
+  const request = typeof body.request === 'string' ? body.request.trim() : ''
+  const reasons = Array.isArray(body.reasons) ? body.reasons.filter((entry) => typeof entry === 'string' && entry !== '') : []
+  if (request === '' && reasons.length === 0) {
+    return sendError(res, 400, 'bad-request', '`request` or `reasons` is required')
+  }
+  const result = await useCases.discussion.discuss({
+    topicKey: 'iterate',
+    label: { zh: '接入新数据源' },
+    cwd: useCases.catalog.workspace,
+    digest: buildIterationBriefing({ request, reasons, question: typeof body.question === 'string' ? body.question : undefined }),
+    // The session has to *do* something: a context-only session queues the
+    // briefing without waking the agent, so the reader would land in an empty
+    // session that never starts. This opening turn makes the session act.
+    question: typeof body.question === 'string' && body.question.trim() !== ''
+      ? body.question.trim()
+      : '请先核对我给的上游接口是否可用（真实字段名与单位），再给出接入计划；需要执行命令时直接执行。',
+    mode: 'new',
+    wait: false,
+    // The iteration session has to *edit this plugin*, so it needs the reader's
+    // composition (file and shell tools); a route cannot see the asking agent, so
+    // the browser names the session.
+    sessionId: typeof body.sessionId === 'string' && body.sessionId !== '' ? body.sessionId : undefined,
+  })
+  if (result.ok !== true) {
+    const kind = result.error?.kind ?? 'internal'
+    const status = kind === 'unavailable' ? 503 : kind === 'bad-request' ? 400 : 502
+    return sendError(res, status, kind, result.error?.detail ?? 'could not open an iteration session', {
+      retryable: result.error?.retryable === true,
+    })
+  }
+  sendJson(res, 200, { sessionId: result.sessionId, pending: result.pending, provider: result.provider, model: result.model })
+}
+
+/**
+ * The briefing an iteration session starts from.
+ *
+ * It states the contract this plugin actually enforces — one adapter file plus one
+ * registry line for a source, one catalog entry plus a recorded fixture for an
+ * indicator — because that constraint is what keeps the change reviewable.
+ *
+ * @param {{ request: string, reasons: string[], question?: string }} input - input.
+ * @returns {string} briefing text.
+ */
+function buildIterationBriefing({ request, reasons, question }) {
+  return [
+    '[数据雷达] 这条消息来自插件面板，不是用户输入。用户想给面板接入新数据源。',
+    '',
+    '插件工作区：本会话的 cwd（就是插件源码根目录）',
+    `用户原始说法：${request === '' ? '（只提供了失败原因）' : request}`,
+    ...(reasons.length === 0 ? [] : ['', '面板无法满足的原因（逐条）：', ...reasons.map((reason) => `- ${reason}`)]),
+    ...(question === undefined || question === '' ? [] : ['', `用户补充：${question}`]),
+    '',
+    '面板当前只读取已登记的数据源，运行时无法新增。请在这个工作区里迭代插件代码来接入，路径是：',
+    '1. 先验证上游接口真的可用（记录 URL、真实字段名、单位、时间口径），不要猜接口；',
+    '2. 新增 `src/sources/<id>.js`：导出 `id`/`label`/`capabilities`/`sourceRef`/`fetchSeries`，并在 `src/sources/registry.js` 加一行；',
+    '3. 在 `src/core/indicators/catalog.js` 增加目录项（`unit`/`freq`/`display.transform` 必须与上游口径一致）；',
+    '4. 用 `RUN_NET=1 node scripts/record-fixtures.mjs --only <adapter>` 录制 fixture，再跑 `node --test "test/**/*.test.js"`；',
+    '5. 需要我执行命令时直接说；插件改动要重启 profile 进程才生效。',
+  ].join('\n')
+}
+
+/**
+ * `GET /discuss/answer?session=…` — collect the answer the session produced.
+ *
+ * The panel opens a discussion with `wait: false` so the GUI can switch to the
+ * new session immediately; this is how it comes back for the text a few seconds
+ * later instead of leaving its own block empty while the answer streams somewhere
+ * the reader has to go and find.
+ *
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @param {URLSearchParams} query - query.
+ * @returns {void} completion.
+ */
+function handleDiscussAnswer(res, useCases, query) {
+  const sessionId = query.get('session')
+  if (sessionId === null || sessionId === '') {
+    return sendError(res, 400, 'bad-request', '`session` is required')
+  }
+  const state = useCases.discussion.answer(sessionId)
+  if (state.status === 'unknown') {
+    // Not ours: the plugin only answers for sessions it opened in this process.
+    return sendError(res, 404, 'unknown-session', `no discussion for session ${sessionId}`)
+  }
+  sendJson(res, 200, state)
+}
+
+/**
+ * `POST /discuss` — open a real session about one indicator and ask the question.
+ *
+ * The panel uses this when the user wants a conversation rather than a one-shot
+ * answer: the reply comes back as text, and the client switches the GUI to the
+ * returned session id so the discussion continues with the full composer.
+ *
+ * @param {import('node:http').IncomingMessage} req - request.
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @returns {Promise<void>} completion.
+ */
+async function handleDiscuss(req, res, useCases) {
+  const body = await readJsonBody(req)
+  const wantGroup = typeof body.group === 'string' && body.group.trim() !== ''
+  const wantIndicator = typeof body.indicator === 'string' && body.indicator.trim() !== ''
+  if (!wantGroup && !wantIndicator) {
+    return sendError(res, 400, 'bad-request', '`indicator` or `group` is required')
+  }
+
+  // Three subjects share one session mechanism, and the panel reaches all three
+  // from a button: one indicator's card, one "worth watching" item, and the whole
+  // panel (optionally narrowed to a group). Only the seeded context differs.
+  //
+  // Every subject also gets a panel-wide *inventory*: one line per indicator the
+  // panel holds. Without it a session seeded with a single block announced that
+  // the panel had no 核心 CPI and no CPI 环比 — both of which it has — and refused
+  // a question it could have answered.
+  const panelInput = await useCases.ai.buildEntries({ range: body.range ?? '1Y', detail: false, noteworthy: 12 })
+  let subject
+  if (wantGroup) {
+    const groups = listParam({ get: () => body.group }, 'group')
+    const digestInput = await useCases.ai.buildEntries({ range: body.range ?? '1Y', groups, noteworthy: body.limit })
+    const noteworthyIds = Array.isArray(body.noteworthy) ? body.noteworthy.filter((id) => typeof id === 'string') : []
+    // A quick question from a notable row still needs the row's numbers, so the
+    // caller may narrow the seeded context to the indicators it is about.
+    const focus = noteworthyIds.length > 0
+      ? digestInput.entries.filter((entry) => noteworthyIds.includes(entry.indicator.id))
+      : digestInput.entries
+    const scoped = focus.length > 0 ? focus : digestInput.entries
+    const detailed = buildDigest(scoped, {
+      budget: DISCUSSION_BUDGET,
+      title: noteworthyIds.length === 1 ? `讨论上下文：${labelOf(useCases, noteworthyIds[0])}` : `讨论上下文：${groups.length === 0 ? '全部指标' : groups.join('+')}`,
+      range: digestInput.range,
+    }).text
+    // The noteworthy block is the *reason* the reader is looking at the panel, so
+    // it travels whole rather than only for the indicator being discussed.
+    const noteworthyText = useCases.ai.buildNoteworthyText(
+      noteworthyIds.length === 1
+        ? (panelInput.noteworthy ?? []).filter((item) => noteworthyIds.includes(item.indicatorId))
+        : panelInput.noteworthy,
+    )
+    const scopeLabel = groups.length === 0 ? '全部指标' : groups.join('+')
+    subject = {
+      kind: noteworthyIds.length === 1 ? 'noteworthy' : 'group',
+      topicKey: noteworthyIds.length === 1 ? noteworthyIds[0] : `group:${groups.length === 0 ? 'ALL' : groups.join('+')}`,
+      label: { zh: noteworthyIds.length === 1 ? labelOf(useCases, noteworthyIds[0]) : `${scopeLabel}（整体）` },
+      digest: [detailed, noteworthyText === '' ? '' : noteworthyText].filter((part) => part !== '').join('\n'),
+      inventory: buildInventory(panelInput.entries, { skip: scoped.map((entry) => entry.indicator.id) }),
+      range: digestInput.range,
+    }
+  } else {
+    const indicatorId = body.indicator
+    const indicator = useCases.catalog.all.find((entry) => entry.id === indicatorId)
+    if (indicator === undefined) {
+      return sendError(res, 404, 'unknown-indicator', `unknown indicator ${indicatorId}`)
+    }
+    // The session is seeded with what the panel shows for this indicator *and* the
+    // indicators that share its subject: a discussion about CPI that cannot see
+    // 核心 CPI or the CPI index is a discussion that answers "data insufficient".
+    const peers = relatedIndicators(useCases.catalog.all, indicatorId)
+    const digestInput = await useCases.ai.buildEntries({
+      range: body.range ?? '1Y',
+      indicators: [indicatorId, ...peers.map((entry) => entry.id)],
+    })
+    const detailed = buildDigest(digestInput.entries, {
+      budget: DISCUSSION_BUDGET,
+      title: `讨论上下文：${indicator.label.zh}${peers.length === 0 ? '' : ` 及相关指标（${peers.map((entry) => entry.label.zh).join('、')}）`}`,
+      range: digestInput.range,
+    }).text
+    const noteworthyText = useCases.ai.buildNoteworthyText(panelInput.noteworthy)
+    subject = {
+      kind: 'indicator',
+      topicKey: indicatorId,
+      indicatorId,
+      label: indicator.label,
+      digest: [detailed, noteworthyText === '' ? '' : noteworthyText].filter((part) => part !== '').join('\n'),
+      inventory: buildInventory(panelInput.entries, { skip: digestInput.entries.map((entry) => entry.indicator.id) }),
+      range: digestInput.range,
+    }
+  }
+
+  const result = await useCases.discussion.discuss({
+    ...subject,
+    question: typeof body.question === 'string' ? body.question : undefined,
+    // The panel's buttons say 「讨论」, not 「自动提问」: when the reader typed
+    // nothing the session still has to run a turn, so it asks the subject's
+    // opening question and reports which one. `ask: false` seeds a session and
+    // leaves the question to whoever opened it.
+    ask: body.ask !== false,
+    mode: body.mode === 'topic' ? 'topic' : 'new',
+    // The panel opens the session immediately and lets it stream there, so it
+    // asks for `wait: false`; a non-GUI caller keeps the synchronous answer.
+    wait: body.wait !== false,
+    // Which session asked. A web route carries no agent, so the browser tells us:
+    // the discussion then inherits the reader's workspace and composition instead
+    // of being created into an empty global layer.
+    sessionId: typeof body.sessionId === 'string' && body.sessionId !== '' ? body.sessionId : undefined,
+  })
+  if (result.ok !== true) {
+    const kind = result.error?.kind ?? 'internal'
+    const status = kind === 'unavailable' ? 503 : kind === 'bad-request' ? 400 : 502
+    // A created session with a failed first turn still has to reach the GUI: an
+    // error response with no session id leaves the reader with a dead button and
+    // a session they cannot find.
+    return sendError(
+      res,
+      status,
+      kind,
+      result.error?.detail ?? 'discussion failed',
+      { retryable: result.error?.retryable === true },
+      {
+        ...(result.sessionId === undefined ? {} : { sessionId: result.sessionId }),
+        ...(result.question === undefined ? {} : { question: result.question, autoQuestion: result.autoQuestion === true }),
+      },
+    )
+  }
+  sendJson(res, 200, {
+    sessionId: result.sessionId,
+    mode: result.mode,
+    reply: result.reply,
+    pending: result.pending,
+    question: result.question,
+    autoQuestion: result.autoQuestion,
+    provider: result.provider,
+    model: result.model,
+    topicKey: subject.topicKey,
+  })
+}
+
+/**
+ * Human label for one indicator id, for a discussion's session title.
+ *
+ * @param {object} useCases - use cases.
+ * @param {string} indicatorId - indicator id.
+ * @returns {string} label.
+ */
+function labelOf(useCases, indicatorId) {
+  return useCases.catalog.all.find((entry) => entry.id === indicatorId)?.label?.zh ?? indicatorId
+}
+
+/**
+ * Run one AI operation, streaming it when asked (docs/06 §1 'AiChunk').
+ *
+ * A streaming response always ends with a 'done' event carrying the validated
+ * 'AiResult', so the client can render the citations even after text has already
+ * been painted.
+ *
+ * @param {import('node:http').ServerResponse} res - response.
+ * @param {object} useCases - use cases.
+ * @param {() => Promise<object>} run - operation.
+ * @param {boolean} stream - whether to stream.
+ * @returns {Promise<void>} completion.
+ */
+async function runAi(res, useCases, run, stream) {
+  if (stream !== true) {
+    const result = await run()
+    return sendJson(res, 200, result)
+  }
+  const write = startSse(res)
+  let result
+  try {
+    result = await run()
+  } catch (error) {
+    const payload = errorPayload(error)
+    write('error', { kind: payload.kind, detail: payload.detail })
+    res.end()
+    return
+  }
+  // Chunk the markdown so the client renders progressively; the digest is small
+  // enough that a coarse chunking keeps the code trivial and the protocol honest.
+  const text = String(result.markdown ?? '')
+  const size = 400
+  for (let i = 0; i < text.length; i += size) {
+    write('text', { text: text.slice(i, i + size) })
+  }
+  write('done', {
+    result: {
+      markdown: result.markdown,
+      usedPoints: result.usedPoints ?? [],
+      insufficient: result.insufficient,
+      mode: result.mode,
+      cached: result.cached === true,
+      fingerprint: result.fingerprint,
+      violations: violationLines(result.violations ?? []),
+    },
+  })
+  res.end()
+}