@ljwei-stak/dsh-model-route-bot 0.66.3 → 0.67.0

package/apps/integration-client/native-activity.mjs

@@ -0,0 +1,384 @@
+// Native tool activity: the honest observation surface.
+//
+// The Host records what a native engine actually did — a tool started, a tool
+// returned, a turn closed, a stop was requested, a stop was confirmed. This
+// module turns those observations into display records and nothing else:
+// it never sends, stops, retries, settles or re-runs anything, and it has no
+// access to a tool's parameters or its result, so it never invents one.
+//
+// The controller is read-only and epoch-guarded. One scope (API instance, Bot,
+// mode, session/context) owns one controller; a reply that does not answer that
+// scope is discarded instead of displayed, and retiring a controller aborts its
+// in-flight read and stops its timer.
+
+const failure = (code, message = code) => Object.assign(new Error(message), { code })
+const BOT = /^[-A-Za-z0-9_.]{1,128}$/
+// Session, context and call keys are Host-minted and opaque, so they are bounded
+// by length and shape only: a format this module invents would refuse real records.
+const ID = /^[^\s\u0000-\u001f\u007f]{1,128}$/
+const KEY = /^[^\s\u0000-\u001f\u007f]{1,256}$/
+const CONTROL = /[\u0000-\u001f\u007f]/
+const OUTCOMES = new Set(['succeeded', 'failed', 'cancelled', 'unknown', 'refused', 'host-closed', 'host-lost'])
+/** The owner action this surface is allowed to call. Nothing else exists here. */
+export const NATIVE_ACTIVITY_ACTION = 'nativeActivity.list'
+export const NATIVE_ACTIVITY_LIMIT_MAX = 50
+export const NATIVE_ACTIVITY_LIMIT_DEFAULT = 20
+/** A loaded page never grows without bound: older rows stop loading, they are never dropped silently. */
+const LOADED_MAX = 200
+const REQUEST_MS = 8000
+
+/** The four states the interface is allowed to show. Nothing else is invented. */
+export const NATIVE_ACTIVITY_STATES = Object.freeze(['running', 'cli-ok', 'cli-error', 'turn-unconfirmed'])
+export const NATIVE_ACTIVITY_LABELS = Object.freeze({
+  running: '进行中',
+  'cli-ok': '已返回',
+  'cli-error': '返回错误',
+  'turn-unconfirmed': '待核对',
+})
+const OUTCOME_WORDS = Object.freeze({
+  succeeded: '已成功返回',
+  failed: '返回失败',
+  cancelled: '已取消',
+  unknown: '结果未知',
+  refused: '被拒绝',
+  'host-closed': '宿主已关闭',
+  'host-lost': '宿主未保留结果',
+})
+
+// Friendly names for the tools a native engine reports. A name the Host did not
+// report stays unreported: the row says "工具调用" and the expanded detail says
+// the name is missing, rather than guessing one.
+const TOOL_WORDS = Object.freeze([
+  { match: /^(?:read|readfile|fileread|view)$/i, label: '读取文件', icon: 'file' },
+  { match: /^(?:write|createfile|filewrite)$/i, label: '写入文件', icon: 'file' },
+  { match: /^(?:edit|multiedit|notebookedit|replace)$/i, label: '修改文件', icon: 'file' },
+  { match: /^(?:bash|shell|command|run|exec|terminal)$/i, label: '运行命令', icon: 'computer' },
+  { match: /^(?:glob|ls|list|find)$/i, label: '查找文件', icon: 'search' },
+  { match: /^(?:grep|search|ripgrep)$/i, label: '搜索内容', icon: 'search' },
+  { match: /^(?:task|agent|subagent)$/i, label: '安排子任务', icon: 'team' },
+  { match: /^(?:todowrite|todos|plan)$/i, label: '更新任务清单', icon: 'tasks' },
+  { match: /^(?:webfetch|fetch|download)$/i, label: '读取网页', icon: 'arrow' },
+  { match: /^(?:websearch|searchweb)$/i, label: '搜索网页', icon: 'search' },
+  { match: /^(?:lsp|diagnostics|typecheck)$/i, label: '检查代码', icon: 'check' },
+])
+
+/** The label and icon one record shows, using only what the Host reported. */
+export function nativeActivityTool(record) {
+  const raw = record?.toolNameRecorded !== false && typeof record?.toolName === 'string' ? record.toolName.trim() : ''
+  const name = raw.startsWith('mcp__') ? raw.split('__').at(-1) : raw
+  const family = {
+    data_load: ['导入数据', 'chart'], data_describe: ['查看数据结构', 'chart'], data_sql: ['查询数据', 'chart'],
+    data_show: ['展示数据', 'chart'], data_export: ['导出数据', 'chart'],
+    bot_file_read: ['读取文件', 'file'], bot_file_write: ['写入文件', 'file'],
+    browser_open: ['打开网页', 'computer'], browser_screenshot: ['网页截图', 'computer'],
+    desktop_screenshot: ['查看桌面', 'computer'], coordinate_bots: ['安排队友工作', 'team'],
+  }[name]
+  if (family) return { label: family[0], icon: family[1], reported: raw }
+  const known = TOOL_WORDS.find(row => row.match.test(name))
+  if (known) return { label: known.label, icon: known.icon, reported: raw }
+  return { label: raw === '' ? '工具调用' : raw, icon: 'bot', reported: raw }
+}
+
+/**
+ * The honest state of one observation.
+ *
+ * A CLI return is not an operation result: `cli-ok` only means the tool answered.
+ * An unknown outcome stays unknown even when a late CLI return arrived, so a late
+ * return can never paint an uncertain row green.
+ */
+export function nativeActivityState(record = {}) {
+  return NATIVE_ACTIVITY_STATES.includes(record?.state) ? record.state : 'turn-unconfirmed'
+}
+
+/** A bounded, readable payload for exactly one scope. */
+export function nativeActivityScope({ botId, mode, sessionId, contextId } = {}) {
+  const hasSession = typeof sessionId === 'string' && sessionId !== ''
+  const hasContext = typeof contextId === 'string' && contextId !== ''
+  if (mode === 'integration') {
+    if (!BOT.test(botId ?? '') || !hasSession || !KEY.test(sessionId) || hasContext) throw failure('NATIVE_ACTIVITY_SCOPE_INVALID', '集成会话缺少有效的 Bot 或会话标识。')
+    return { botId, mode: 'integration', sessionId, contextId: null }
+  }
+  if (mode === 'independent') {
+    if (!BOT.test(botId ?? '') || !hasContext || !ID.test(contextId) || hasSession) throw failure('NATIVE_ACTIVITY_SCOPE_INVALID', '独立会话缺少有效的 Bot 或对话标识。')
+    return { botId, mode: 'independent', sessionId: null, contextId }
+  }
+  throw failure('NATIVE_ACTIVITY_SCOPE_INVALID', '工具记录读取模式无效。')
+}
+
+/** The stable identity of one scope: a change here is an epoch boundary. */
+export function nativeActivityScopeKey({ botId, mode, sessionId, contextId } = {}) {
+  const scope = nativeActivityScope({ botId, mode, sessionId, contextId })
+  return `${scope.mode}:${scope.botId}:${scope.sessionId ?? ''}:${scope.contextId ?? ''}`
+}
+
+const payloadOf = (scope, cursor, limit) => ({
+  botId: scope.botId,
+  mode: scope.mode,
+  ...(scope.mode === 'integration' ? { sessionId: scope.sessionId } : { contextId: scope.contextId }),
+  limit,
+  ...(cursor ? { cursor } : {}),
+})
+
+const text = (value, max) => typeof value === 'string' && value !== '' && value.length <= max && !CONTROL.test(value) ? value : null
+const count = value => Number.isSafeInteger(value) && value >= 0 ? value : null
+
+/** One display record. A field the Host did not send stays null; nothing is filled in. */
+function readRecord(value, scope) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.schemaVersion !== 1) return null
+  const callKey = text(value.callKey, 128), callId = text(value.callId, 256)
+  if (callKey === null || !KEY.test(callKey) || callId === null || !KEY.test(callId)
+    || text(value.turnId, 128) === null || text(value.processGeneration, 128) === null
+    || !NATIVE_ACTIVITY_STATES.includes(value.state) || count(value.startedAt) === null || count(value.updatedAt) === null
+    || value.endedAt !== null && count(value.endedAt) === null
+    || value.cliOk !== null && typeof value.cliOk !== 'boolean'
+    || value.turnOutcome !== null && !OUTCOMES.has(value.turnOutcome)) return null
+  if (['toolNameRecorded', 'turnSettled', 'cancelRequested', 'stopConfirmed', 'lateCliReturn'].some(key => typeof value[key] !== 'boolean')
+    || value.state === 'cli-ok' && value.cliOk !== true || value.state === 'cli-error' && value.cliOk !== false
+    || ['running', 'turn-unconfirmed'].includes(value.state) && value.cliOk !== null) return null
+  if (value.botId !== scope.botId || value.mode !== scope.mode || value.conversationId !== scope.conversationId
+    || value.contextId !== scope.contextId) throw failure('NATIVE_ACTIVITY_SCOPE_MISMATCH', '工具记录属于其他会话。')
+  const record = {
+    schemaVersion: 1, callKey, callId,
+    botId: value.botId, mode: value.mode, conversationId: value.conversationId, contextId: value.contextId,
+    processGeneration: value.processGeneration, turnId: value.turnId,
+    toolName: value.toolNameRecorded === false ? null : text(value.toolName, 128),
+    toolNameRecorded: value.toolNameRecorded === true,
+    state: value.state, cliOk: value.cliOk, turnOutcome: value.turnOutcome, turnSettled: value.turnSettled === true,
+    startedAt: value.startedAt, endedAt: value.endedAt, updatedAt: value.updatedAt,
+    cancelRequested: value.cancelRequested === true,
+    stopConfirmed: value.stopConfirmed === true,
+    lateCliReturn: value.lateCliReturn === true,
+    lateCliOk: value.lateCliOk === true ? true : value.lateCliOk === false ? false : null,
+    duplicateStarts: count(value.duplicateStarts) ?? 0, duplicateCompletions: count(value.duplicateCompletions) ?? 0,
+  }
+  return record
+}
+
+/**
+ * A closed page for exactly this scope. A page that cannot be read completely is
+ * refused instead of shown partially, so a gap can never look like finished work.
+ */
+export function readNativeActivityPage(value, scope) {
+  if (!value || typeof value !== 'object' || value.schemaVersion !== 1) throw failure('NATIVE_ACTIVITY_INVALID', '宿主返回的工具记录格式无效。')
+  const reply = value.scope
+  if (!reply || typeof reply !== 'object' || reply.botId !== scope.botId || reply.mode !== scope.mode) throw failure('NATIVE_ACTIVITY_SCOPE_MISMATCH', '宿主回答的不是当前会话。')
+  if (scope.mode === 'integration') {
+    if (reply.sessionId !== scope.sessionId || text(reply.conversationId, 128) === null || reply.contextId !== null) throw failure('NATIVE_ACTIVITY_SCOPE_MISMATCH', '宿主回答的不是当前集成会话。')
+  } else if (reply.sessionId !== null || reply.contextId !== scope.contextId || reply.conversationId !== scope.contextId) throw failure('NATIVE_ACTIVITY_SCOPE_MISMATCH', '宿主回答的不是当前对话。')
+  if (!Array.isArray(value.items) || value.items.length > NATIVE_ACTIVITY_LIMIT_MAX) throw failure('NATIVE_ACTIVITY_INVALID', '宿主返回的工具记录数量无效。')
+  const items = []
+  for (const row of value.items) {
+    const record = readRecord(row, reply)
+    if (record === null) throw failure('NATIVE_ACTIVITY_INVALID', '宿主返回的工具记录缺少稳定编号。')
+    items.push(record)
+  }
+  if (new Set(items.map(row => row.callKey)).size !== items.length) throw failure('NATIVE_ACTIVITY_INVALID', '宿主返回的工具记录编号重复。')
+  if (typeof value.nativeRoute !== 'boolean') throw failure('NATIVE_ACTIVITY_INVALID', '宿主没有说明这一会话是否记录工具活动。')
+  const recording = value.recording
+  if (!recording || typeof recording !== 'object' || !['ready', 'degraded'].includes(recording.status)
+    || count(recording.failures) === null) throw failure('NATIVE_ACTIVITY_INVALID', '宿主没有说明工具记录写入状态。')
+  const nextCursor = value.nextCursor === null ? null : text(value.nextCursor, 4096)
+  if (value.nextCursor !== null && nextCursor === null) throw failure('NATIVE_ACTIVITY_INVALID', '宿主返回的记录页码无效。')
+  return {
+    conversationId: text(reply.conversationId, 128),
+    contextId: scope.mode === 'independent' ? scope.contextId : null,
+    items,
+    nextCursor,
+    nativeRoute: value.nativeRoute,
+    recording: { status: recording.status, failures: count(recording.failures), code: text(recording.code, 64) },
+  }
+}
+
+// Newest first, then by call key, exactly the order the Host commits to. The
+// order is display only: every record keeps the identity it arrived with.
+const compareRecords = (a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0)
+  || (a.callKey < b.callKey ? 1 : a.callKey > b.callKey ? -1 : 0)
+
+/**
+ * The reported result is stable, while later cancellation, stop and settlement
+ * facts still arrive. Unknown never becomes green, and an older page cannot
+ * overwrite a newer observation.
+ */
+const mergeRecord = (held, next) => {
+  for (const key of ['botId', 'mode', 'conversationId', 'contextId', 'processGeneration', 'turnId', 'callId', 'startedAt']) {
+    if (held[key] !== next[key]) throw failure('NATIVE_ACTIVITY_SCOPE_MISMATCH', '工具记录的原始身份发生变化。')
+  }
+  return { ...next,
+    state: held.state === 'running' ? next.state : held.state,
+    cliOk: held.state === 'running' ? next.cliOk : held.cliOk,
+    toolName: held.toolNameRecorded ? held.toolName : next.toolName,
+    toolNameRecorded: held.toolNameRecorded || next.toolNameRecorded,
+    endedAt: held.endedAt ?? next.endedAt,
+    turnOutcome: held.turnSettled ? held.turnOutcome : next.turnOutcome,
+    turnSettled: held.turnSettled || next.turnSettled,
+    cancelRequested: held.cancelRequested || next.cancelRequested,
+    stopConfirmed: held.stopConfirmed || next.stopConfirmed,
+    lateCliReturn: held.lateCliReturn || next.lateCliReturn,
+    lateCliOk: held.lateCliReturn ? held.lateCliOk : next.lateCliOk,
+    duplicateStarts: Math.max(held.duplicateStarts, next.duplicateStarts),
+    duplicateCompletions: Math.max(held.duplicateCompletions, next.duplicateCompletions),
+    updatedAt: Math.max(held.updatedAt, next.updatedAt),
+  }
+}
+
+function mergeRecords(previous, incoming) {
+  const byKey = new Map(previous.map(row => [row.callKey, row]))
+  for (const row of incoming) {
+    const held = byKey.get(row.callKey)
+    byKey.set(row.callKey, held === undefined ? row : mergeRecord(held, row))
+  }
+  const items = [...byKey.values()].sort(compareRecords)
+  return { items: items.length > LOADED_MAX ? items.slice(0, LOADED_MAX) : items, truncated: items.length > LOADED_MAX }
+}
+
+/** The view crop. Paging reads the original records; this only chooses how many are shown. */
+export const nativeActivityLatest = (items, count = 4) => items.slice(0, count)
+
+/** What the compact surface says, using only loaded records. */
+export function nativeActivitySummary(items) {
+  const rows = Array.isArray(items) ? items : []
+  const running = rows.find(row => row.state === 'running')
+  if (running) {
+    const tool = nativeActivityTool(running)
+    return { state: 'running', text: `正在进行：${tool.label}`, icon: tool.icon, record: running }
+  }
+  const first = rows[0]
+  if (!first) return null
+  const tool = nativeActivityTool(first)
+  return { state: first.state, text: `最近：${tool.label} · ${NATIVE_ACTIVITY_LABELS[first.state]}`, icon: tool.icon, record: first }
+}
+
+export const nativeActivityOutcomeWord = outcome => (outcome && OUTCOME_WORDS[outcome]) || '宿主未记录结果'
+
+/** A read failure in the owner's words. Raw transport detail never reaches the screen. */
+export function nativeActivityNote(error) {
+  switch (error?.code) {
+    case 'NATIVE_ACTIVITY_SCOPE_INVALID': return '当前会话的工具记录范围无效，已停止读取。'
+    case 'NATIVE_ACTIVITY_SCOPE_MISMATCH': return '宿主切换了这一会话的工具记录范围，已停止显示之前的内容。'
+    case 'NATIVE_ACTIVITY_INVALID': return '宿主返回的工具记录无法核对，这一页已拒绝显示。'
+    case 'NATIVE_ACTIVITY_ABORTED': return '宿主没有在约定时间内回答，已保留上一次读到的记录。'
+    case 'NATIVE_ACTIVITY_UNAVAILABLE': return '当前宿主暂不支持读取工具记录。'
+    default: return '读取工具记录失败，已保留上一次读到的记录。'
+  }
+}
+
+export const nativeActivityRecordingNote = recording => recording?.status === 'degraded'
+  ? '工具记录写入异常，下面只显示已经记下的部分，可能不完整。'
+  : ''
+
+/** `14:20` today, `11-09 14:20` otherwise; an unrecorded time says so. */
+export function formatActivityAt(value, now = Date.now()) {
+  if (!Number.isSafeInteger(value) || value <= 0) return '时间未记录'
+  const at = new Date(value), today = new Date(now)
+  const clock = `${String(at.getHours()).padStart(2, '0')}:${String(at.getMinutes()).padStart(2, '0')}`
+  const sameDay = at.getFullYear() === today.getFullYear() && at.getMonth() === today.getMonth() && at.getDate() === today.getDate()
+  return sameDay ? clock : `${String(at.getMonth() + 1).padStart(2, '0')}-${String(at.getDate()).padStart(2, '0')} ${clock}`
+}
+
+/**
+ * One mounted, read-only observation of one scope.
+ *
+ * Polling exists only while this controller is live and only for this scope:
+ * dispose() clears the timer and aborts the in-flight read, and every reply is
+ * checked against the epoch that asked for it, so a late answer for a retired
+ * Host, API, Bot, session or context is dropped instead of displayed.
+ */
+export function createNativeActivityController({
+  api, botId, mode, sessionId, contextId,
+  pollMs = 1500, limit = NATIVE_ACTIVITY_LIMIT_DEFAULT, timeoutMs = REQUEST_MS,
+} = {}) {
+  const scope = nativeActivityScope({ botId, mode, sessionId, contextId })
+  const readLimit = Number.isSafeInteger(limit) ? Math.min(Math.max(1, limit), NATIVE_ACTIVITY_LIMIT_MAX) : NATIVE_ACTIVITY_LIMIT_DEFAULT
+  if (typeof api?.dispatch !== 'function') throw failure('NATIVE_ACTIVITY_UNAVAILABLE', '宿主没有提供只读工具记录接口。')
+  const listeners = new Set(), inflight = new Set()
+  let live = false, retired = false, fenced = false, reading = false, paging = false, timer
+  let pollEpoch = 0, pageEpoch = 0, pagingStarted = false
+  let state = {
+    scope, conversationId: null, items: [], latest: [], nextCursor: null,
+    loading: true, loadingOlder: false, error: '', code: null, truncated: false, loaded: false,
+    nativeRoute: null, recording: { status: null, failures: 0, code: null }, revision: 0,
+  }
+  const publish = patch => {
+    if (retired) return
+    state = { ...state, ...patch, latest: nativeActivityLatest((patch.items ?? state.items)) , revision: state.revision + 1 }
+    for (const listener of listeners) listener()
+  }
+  const list = async (cursor, signal) => {
+    let cancel
+    const interrupted = new Promise((_resolve, reject) => {
+      cancel = () => reject(failure('NATIVE_ACTIVITY_ABORTED', '读取已中断。'))
+      signal.addEventListener('abort', cancel, { once: true })
+      if (signal.aborted) cancel()
+    })
+    try { return await Promise.race([Promise.resolve().then(() => api.dispatch(NATIVE_ACTIVITY_ACTION, payloadOf(scope, cursor, readLimit), signal)), interrupted]) }
+    finally { signal.removeEventListener('abort', cancel) }
+  }
+  const fail = error => {
+    const mismatched = error?.code === 'NATIVE_ACTIVITY_SCOPE_MISMATCH'
+    if (mismatched) fenced = true
+    publish({ loading: false, error: nativeActivityNote(error), code: typeof error?.code === 'string' ? error.code : null,
+      ...(mismatched ? { items: [], nextCursor: null, loaded: false } : {}) })
+  }
+  const applyPage = (page, olderPage = false) => {
+    if (state.conversationId !== null && page.conversationId !== state.conversationId) {
+      fenced = true
+      fail(failure('NATIVE_ACTIVITY_SCOPE_MISMATCH'))
+      return
+    }
+    const merged = mergeRecords(state.items, page.items)
+    const truncated = state.truncated || merged.truncated
+    publish({
+      items: merged.items, truncated, nextCursor: truncated ? null : olderPage || !pagingStarted ? page.nextCursor : state.nextCursor,
+      conversationId: page.conversationId, nativeRoute: page.nativeRoute, recording: page.recording,
+      loading: false, loaded: true, error: '', code: null,
+    })
+  }
+  const refresh = async () => {
+    if (!live || fenced) return
+    if (reading || paging) { clearTimeout(timer); timer = setTimeout(refresh, pollMs); return }
+    reading = true
+    publish({ loading: true })
+    const mine = ++pollEpoch
+    const controller = new AbortController()
+    inflight.add(controller)
+    const alarm = setTimeout(() => controller.abort(), timeoutMs)
+    try {
+      const page = readNativeActivityPage(await list(null, controller.signal), scope)
+      if (!live || mine !== pollEpoch || controller.signal.aborted) return
+      applyPage(page)
+    } catch (error) { if (live && mine === pollEpoch) fail(error) }
+    finally {
+      clearTimeout(alarm); reading = false; inflight.delete(controller)
+      if (live && !fenced) { clearTimeout(timer); timer = setTimeout(refresh, pollMs) }
+    }
+  }
+  const older = async () => {
+    if (!live || paging || reading || fenced || state.truncated || state.nextCursor === null) return
+    pagingStarted = true
+    paging = true
+    publish({ loadingOlder: true })
+    const mine = ++pageEpoch
+    const cursor = state.nextCursor
+    const controller = new AbortController()
+    inflight.add(controller)
+    const alarm = setTimeout(() => controller.abort(), timeoutMs)
+    try {
+      const page = readNativeActivityPage(await list(cursor, controller.signal), scope)
+      if (!live || mine !== pageEpoch || controller.signal.aborted) return
+      applyPage(page, true)
+    } catch (error) { if (live && mine === pageEpoch) fail(error) }
+    finally { clearTimeout(alarm); paging = false; inflight.delete(controller); if (live) publish({ loadingOlder: false }) }
+  }
+  return Object.freeze({
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener) },
+    getSnapshot: () => state,
+    start() { if (retired || live || fenced) return; live = true; void refresh() },
+    inspect() { clearTimeout(timer); void refresh() },
+    older,
+    dispose() {
+      live = false; retired = true; fenced = true; clearTimeout(timer)
+      for (const controller of inflight) controller.abort()
+      inflight.clear(); listeners.clear()
+    },
+  })
+}

package/apps/integration-client/notifications-panel.jsx

@@ -0,0 +1,186 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react'
+import { UiIcon } from './ui-icons.jsx'
+
+// A read-only inbox over committed Task-journal events. It opens the original
+// detail and tracks what the owner has seen; it never starts, stops or retries a
+// Task, and it renders only the Host's structured projection (never task input,
+// execution references or raw event detail).
+const PAGE = 20
+const VISIBLE_MS = 5000
+const FAILED_MS = 15000
+const MAX_ITEMS = 200
+
+function abortable(work, signal) {
+  let cancel
+  const interrupted = new Promise((_resolve, reject) => {
+    cancel = () => reject(new Error('NOTIFICATION_REQUEST_ABORTED'))
+    signal.addEventListener('abort', cancel, { once: true })
+    if (signal.aborted) cancel()
+  })
+  return Promise.race([Promise.resolve().then(work), interrupted]).finally(() => signal.removeEventListener('abort', cancel))
+}
+
+const CATEGORY_ICON = { succeeded: 'check', failed: 'close', reconcile: 'refresh', 'waiting-budget': 'clock', cancelled: 'close', blocked: 'lock', reconciled: 'check', update: 'activity' }
+
+// Merge a freshly-read newest page into the rendered list. Keys are the durable
+// event seq, so a row the owner is focused on keeps its DOM node across a poll.
+function merge(existing, incoming) {
+  const map = new Map(existing.map(item => [item.seq, item]))
+  for (const item of incoming) map.set(item.seq, item)
+  return [...map.values()].sort((left, right) => right.seq - left.seq).slice(0, MAX_ITEMS)
+}
+
+/** Relative time from structured journal state; `now` is injected so it stays testable. */
+export function formatAt(at, now = Date.now()) {
+  if (!Number.isSafeInteger(at) || at < 0) return ''
+  const seconds = Math.max(0, Math.round((now - at) / 1000))
+  if (seconds < 45) return '刚刚'
+  const minutes = Math.round(seconds / 60)
+  if (minutes < 60) return `${minutes} 分钟前`
+  const hours = Math.round(minutes / 60)
+  if (hours < 24) return `${hours} 小时前`
+  return `${Math.round(hours / 24)} 天前`
+}
+
+let scopeKey = 0
+export function NotificationsPanel(props) {
+  const key = useMemo(() => ++scopeKey, [props.productApi, props.available])
+  return <NotificationFeed key={key} {...props} />
+}
+
+function NotificationFeed({ productApi, onNavigate, available = true, botIds }) {
+  const [items, setItems] = useState([])
+  const [summary, setSummary] = useState(null)
+  const [status, setStatus] = useState(available ? 'loading' : 'unavailable')
+  const [loadingMore, setLoadingMore] = useState(false)
+  const [pending, setPending] = useState(false)
+  const [feedback, setFeedback] = useState('')
+  const session = useRef({ live: false, epoch: 0, busy: false, requests: new Set() })
+
+  // Each operation is retired with its Host. A read acknowledgement must arrive
+  // before the UI claims success; stale polls cannot overwrite that receipt.
+  const requestAction = async (action, payload, apply) => {
+    const current = session.current
+    if (!current.live || current.busy) return
+    current.busy = true; current.epoch++
+    for (const controller of current.requests) controller.abort()
+    const controller = new AbortController()
+    current.requests.add(controller)
+    setPending(true); setFeedback('')
+    const timeout = setTimeout(() => controller.abort(), 8000)
+    try {
+      const result = await abortable(() => productApi.dispatch(action, payload, controller.signal), controller.signal)
+      if (current.live && !controller.signal.aborted) apply(result)
+    } catch {
+      if (current.live) setFeedback(action === 'notifications.list' ? '较早通知暂时无法读取，请重试。' : '已读状态未确认，请重试。')
+    } finally {
+      clearTimeout(timeout); current.requests.delete(controller); current.busy = false
+      if (current.live) { setPending(false); setLoadingMore(false) }
+    }
+  }
+
+  useEffect(() => {
+    if (!available || typeof productApi?.dispatch !== 'function') { setStatus('unavailable'); return undefined }
+    let live = true, epoch = 0, timer, request
+    const currentSession = session.current
+    currentSession.live = true
+    const schedule = (delay) => { clearTimeout(timer); if (live && !document.hidden) timer = setTimeout(load, delay) }
+    const load = async () => {
+      clearTimeout(timer)
+      if (!live || document.hidden) return
+      if (currentSession.busy) { schedule(VISIBLE_MS); return }
+      const current = ++epoch, controller = new AbortController()
+      const revision = currentSession.epoch
+      request?.abort(); request = controller
+      currentSession.requests.add(controller)
+      const deadline = setTimeout(() => controller.abort(), 8000)
+      const valid = () => live && current === epoch && revision === currentSession.epoch && !controller.signal.aborted
+      let failed = false
+      try {
+        const page = await abortable(() => productApi.dispatch('notifications.list', { limit: PAGE }, controller.signal), controller.signal)
+        if (!valid()) return
+        setItems(previous => merge(previous, Array.isArray(page?.items) ? page.items : []))
+        setSummary(previous => ({ unreadCount: page?.unreadCount ?? 0, truncated: page?.truncated === true,
+          nextBefore: previous?.olderLoaded ? previous.nextBefore : page?.nextBefore ?? null, olderLoaded: previous?.olderLoaded ?? false, maxSeq: page?.maxSeq ?? 0 }))
+        setStatus('ready')
+      } catch {
+        failed = true
+        // A transient failure keeps the rows already on screen; only a first
+        // load that never succeeded reports an error state.
+        if (live && current === epoch && revision === currentSession.epoch) setStatus('error')
+      } finally {
+        clearTimeout(deadline)
+        currentSession.requests.delete(controller)
+        if (request === controller) request = undefined
+        if (live && current === epoch) schedule(failed ? FAILED_MS : VISIBLE_MS)
+      }
+    }
+    const visible = () => { if (document.hidden) { epoch++; clearTimeout(timer); request?.abort(); request = undefined } else void load() }
+    document.addEventListener('visibilitychange', visible)
+    void load()
+    return () => { live = false; currentSession.live = false; epoch++; clearTimeout(timer); for (const controller of currentSession.requests) controller.abort(); document.removeEventListener('visibilitychange', visible) }
+  }, [productApi, available])
+
+  const open = item => { if (typeof onNavigate === 'function') onNavigate({ section: 'tasks', botId: item.botId, taskId: item.taskId, attemptId: item.attemptId }) }
+  const markRead = item => requestAction('notifications.read', { seq: item.seq }, result => {
+    setItems(previous => previous.map(row => row.seq === item.seq ? { ...row, read: true } : row))
+    setSummary(previous => ({ ...previous, unreadCount: result.unreadCount, truncated: result.truncated === true }))
+  })
+  const markAll = () => requestAction('notifications.markAll', {}, result => {
+    setItems(previous => previous.map(row => row.seq <= result.cursorSeq ? { ...row, read: true } : row))
+    setSummary(previous => ({ ...previous, unreadCount: result.unreadCount, truncated: result.truncated === true }))
+  })
+  const loadMore = async () => {
+    if (loadingMore || summary?.nextBefore === null || summary?.nextBefore === undefined) return
+    setLoadingMore(true)
+    await requestAction('notifications.list', { before: summary.nextBefore, limit: PAGE }, page => {
+      setItems(previous => merge(previous, Array.isArray(page?.items) ? page.items : []))
+      setSummary(previous => ({ ...previous, nextBefore: page?.nextBefore ?? null, olderLoaded: true }))
+    })
+  }
+
+  const unread = summary?.unreadCount ?? 0
+  const shown = Array.isArray(botIds) ? items.filter(item => botIds.includes(item.botId)) : items
+  return (
+    <section className="bp-notifications" aria-label="通知中心">
+      <header className="bp-notifications-bar">
+        <h2 className="bp-notifications-title">通知中心</h2>
+        {(unread > 0 || summary?.truncated) && <span className="bp-notifications-badge" aria-label={unread ? `${summary?.truncated ? '至少 ' : ''}${unread} 条未读` : '较早通知的未读状态尚未完整统计'}>{unread > 99 ? '99+' : unread ? `${unread}${summary?.truncated ? '+' : ''}` : '…'}</span>}
+        <div className="bp-notifications-bar-actions">
+          <button type="button" className="bp-notifications-markall" onClick={markAll} disabled={pending || (unread === 0 && !summary?.truncated)}>
+            <UiIcon name="check" size={16} /><span>全部已读</span>
+          </button>
+        </div>
+      </header>
+      {feedback && <p className="bp-notifications-note" role="alert">{feedback}</p>}
+      {summary?.truncated && <p className="bp-notifications-note">未读数量仅统计最近 512 条事件，可继续查看历史通知。</p>}
+      {status === 'unavailable' && <p className="bp-notifications-note">当前连接暂时无法读取通知。恢复可用连接后，可在这里查看任务完成、失败与待核对事件。</p>}
+      {status === 'loading' && <p className="bp-notifications-note" role="status">正在读取通知…</p>}
+      {status === 'error' && <p className="bp-notifications-note" role="status">通知暂时没有更新，稍后会自动重试。</p>}
+      {status === 'ready' && shown.length === 0 && <p className="bp-notifications-note">暂无通知。任务完成、失败或需要核对时会出现在这里。</p>}
+      {shown.length > 0 && (
+        <ul className="bp-notifications-list">
+          {shown.map(item => (
+            <li key={item.seq} className={`bp-notification bp-notification-${item.tone}${item.read ? '' : ' is-unread'}`} data-category={item.category} data-seq={item.seq}>
+              <button type="button" className="bp-notification-open" onClick={() => open(item)}>
+                <span className="bp-notification-icon" aria-hidden="true"><UiIcon name={CATEGORY_ICON[item.category] ?? 'activity'} size={18} /></span>
+                <span className="bp-notification-body">
+                  <span className="bp-notification-text">{item.text}</span>
+                  <span className="bp-notification-meta">
+                    {item.isNew && <span className="bp-notification-new">新</span>}
+                    <span className="bp-notification-time">{formatAt(item.at)}</span>
+                  </span>
+                </span>
+                {!item.read && <span className="bp-notification-dot" aria-label="未读" />}
+              </button>
+              {!item.read && <button type="button" className="bp-notification-read" disabled={pending} onClick={() => markRead(item)} aria-label="标为已读"><UiIcon name="check" size={16} /></button>}
+            </li>
+          ))}
+        </ul>
+      )}
+      {summary?.nextBefore !== null && summary?.nextBefore !== undefined && items.length > 0 && (
+        <button type="button" className="bp-notifications-more" onClick={loadMore} disabled={pending || loadingMore || items.length >= MAX_ITEMS}>{loadingMore ? '加载中…' : items.length >= MAX_ITEMS ? '已显示最近 200 条通知' : '加载更早'}</button>
+      )}
+    </section>
+  )
+}