cx-chat 0.0.1

package/src/views/chat/components/message-list/preparation-steps.tsx

@@ -0,0 +1,506 @@
+import type { Message } from '@/types'
+import type { TFunction } from 'i18next'
+import clsx from 'clsx'
+import { CxSteps } from '@cx-ui'
+import type { StepsProps } from 'antd'
+import { Spin } from 'antd'
+import { CheckCircle2 } from 'lucide-react'
+import React from 'react'
+import { useTranslation } from 'react-i18next'
+import type { Components } from 'react-markdown'
+import ReactMarkdown from 'react-markdown'
+import remarkGfm from 'remark-gfm'
+
+// i18n 中文：locales/zh/chat.ts（chat.preparation_heading → 正在分析）
+// 样式：views/chat/chat.less（chat-prep-*、chat-prep-step-desc-scroll、--memory-tail 含知识库检索、chat-prep-step-md）
+// DEV 演示数据：preparation-demo-items.ts（CHAT_PREPARATION_DEMO_ITEMS，与 SSE preparation 对齐）
+// 与 use-message-list-scroll 约定：chat-prep-layout 事件（副标题区布局增高时粘底）
+// 副标题串行：按 preparation 行顺序，上一行打字播完再开始下一行（无副标题行自动跳过）
+
+/** 消息列表在「靠近底部」时响应此事件做粘底（use-message-list-scroll 内监听同名） */
+export const CHAT_MESSAGE_LIST_PREP_LAYOUT_EVENT = 'chat-prep-layout'
+
+let prepLayoutBumpTimer: ReturnType<typeof setTimeout> | null = null
+
+function bumpChatMessageListPrepLayout() {
+  if (prepLayoutBumpTimer != null) return
+  prepLayoutBumpTimer = setTimeout(() => {
+    prepLayoutBumpTimer = null
+    window.dispatchEvent(new CustomEvent(CHAT_MESSAGE_LIST_PREP_LAYOUT_EVENT))
+  }, 40)
+}
+
+/** preparation 副标题：GFM Markdown；真实换行或字面量 `\n` 均可，`\n\n` 分段落 */
+const prepDescriptionMarkdownComponents: Components = {
+  a: (props) => (
+    <a {...props} target="_blank" rel="noopener noreferrer" />
+  ),
+}
+
+/** 将接口里常见的字面量转义还原（如 JSON 里写成 `\\n` 解析后仍是反斜杠+n） */
+function preparationDescriptionUnescapeSequences(raw: string) {
+  return raw
+    .replace(/\\r\\n/g, '\n')
+    .replace(/\\r/g, '\n')
+    .replace(/\\n/g, '\n')
+    .replace(/\\t/g, '\t')
+}
+
+function normalizePreparationDescriptionRaw(raw: string) {
+  return preparationDescriptionUnescapeSequences(raw.trim())
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+}
+
+function preparationDescriptionToMarkdownFromNormalized(normalized: string) {
+  return normalized
+    .split(/\n\n/)
+    .map((block) => block.replace(/\n/g, '  \n'))
+    .join('\n\n')
+}
+
+/** 副标题打字机：每档间隔（ms），与「每档字符数」配合控制整体节奏（略快于逐字、慢于一帧刷满） */
+const PREP_DESC_CHUNK_TICK_MS = 44
+
+function prepDescCharsPerTick(len: number) {
+  return Math.max(2, Math.ceil(len / 88))
+}
+
+/** 短期/长期记忆、知识库检索：固定可视约 4 行、裁切顶部、无滚动（与 --memory-tail 样式一致） */
+function isPrepMemoryTailViewStep(code: string) {
+  return (
+    code === 'short_memory' ||
+    code === 'long_memory' ||
+    code === 'knowledge_retrieval'
+  )
+}
+
+/** 无后端 description 时，用参考资料列表拼成副标题（与右侧面板语义一致，键见 locales/zh/chat.ts） */
+function buildKnowledgeRetrievalPrepDescriptionFromRefs(
+  refItems: NonNullable<Message['references_knowledge_items']>,
+  t: TFunction,
+) {
+  if (!refItems.length) return ''
+  const blocks = refItems.map((x, idx) => {
+    const docName =
+      (typeof x.doc_name === 'string' && x.doc_name) ||
+      (typeof x.docName === 'string' && x.docName) ||
+      ''
+    const titleLine = docName
+      ? t('chat.references_item_with_doc', { index: idx + 1, docName }) // 资料 n（文档名）
+      : t('chat.references_item_plain', { index: idx + 1 }) // 资料 n
+    const rawBody =
+      typeof x.page_content === 'string' ? x.page_content.trim() : ''
+    const body =
+      rawBody || t('chat.references_excerpt_placeholder') // 正文占位
+    const kbName =
+      typeof x.kb_name === 'string' && x.kb_name.trim()
+        ? x.kb_name.trim()
+        : '-'
+    const kbLine = `${t('chat.references_kb_label')}${kbName}` // 知识库：+ 名称
+    return `${titleLine}\n${body}\n${kbLine}`
+  })
+  return blocks.join('\n\n---\n\n')
+}
+
+function PreparationStepDescriptionMd({
+  source,
+  stepCode,
+  rowKey,
+  revealMode,
+  onRevealStart,
+  onRevealComplete,
+}: {
+  source: string
+  /** 当前 preparation 项 code：记忆类与知识库检索走尾部裁切、不可滚可视区 */
+  stepCode: string
+  /** 与父级 Steps 行一致，用于打字开始/结束回调 */
+  rowKey: string
+  /** full：已轮到且之前阶段已播完，整段展示；typing：当前串行阶段，块打字机 */
+  revealMode: 'full' | 'typing'
+  /** 开始从 0 揭示前调用（父级将本行标为未完成，避免 Strict Mode 下图标先打勾） */
+  onRevealStart?: (key: string) => void
+  /** 本行副标题揭示到满字时调用一次 */
+  onRevealComplete?: (key: string) => void
+}) {
+  const normalizedFull = React.useMemo(
+    () => normalizePreparationDescriptionRaw(source),
+    [source],
+  )
+  const [revealedLen, setRevealedLen] = React.useState(0)
+  const descScrollRef = React.useRef<HTMLDivElement>(null)
+  const prevNormRef = React.useRef<string | null>(null)
+  const revealDoneNotifiedRef = React.useRef(false)
+
+  const memoryTailView = isPrepMemoryTailViewStep(stepCode)
+
+  const scrollDescRefToEnd = React.useCallback(() => {
+    if (!memoryTailView) {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          const el = descScrollRef.current
+          if (el) el.scrollTop = el.scrollHeight
+          bumpChatMessageListPrepLayout()
+        })
+      })
+    } else {
+      bumpChatMessageListPrepLayout()
+    }
+  }, [memoryTailView])
+
+  React.useLayoutEffect(() => {
+    if (revealMode !== 'full') return
+    const len = normalizedFull.length
+    if (!len) {
+      setRevealedLen(0)
+      return
+    }
+    setRevealedLen(len)
+    scrollDescRefToEnd()
+  }, [revealMode, normalizedFull, scrollDescRefToEnd])
+
+  React.useEffect(() => {
+    if (revealMode !== 'typing') return
+
+    if (prevNormRef.current !== normalizedFull) {
+      prevNormRef.current = normalizedFull
+      revealDoneNotifiedRef.current = false
+    }
+
+    const len = normalizedFull.length
+    if (!len) {
+      setRevealedLen(0)
+      return
+    }
+
+    onRevealStart?.(rowKey)
+    setRevealedLen(0)
+    const t0 = performance.now()
+    let rafId = 0
+    let revealed = 0
+    const tickMs = PREP_DESC_CHUNK_TICK_MS
+    const chunk = prepDescCharsPerTick(len)
+    let nextTickAt = t0 + tickMs
+
+    const step = (now: number) => {
+      if (now >= nextTickAt && revealed < len) {
+        revealed = Math.min(len, revealed + chunk)
+        nextTickAt = now + tickMs
+        setRevealedLen(revealed)
+        scrollDescRefToEnd()
+      }
+
+      if (revealed >= len) {
+        if (!revealDoneNotifiedRef.current) {
+          revealDoneNotifiedRef.current = true
+          onRevealComplete?.(rowKey)
+        }
+        return
+      }
+
+      rafId = requestAnimationFrame(step)
+    }
+
+    rafId = requestAnimationFrame(step)
+    return () => {
+      cancelAnimationFrame(rafId)
+    }
+  }, [
+    revealMode,
+    normalizedFull,
+    scrollDescRefToEnd,
+    memoryTailView,
+    rowKey,
+    onRevealStart,
+    onRevealComplete,
+  ])
+
+  if (!normalizedFull.length) return null
+
+  const md = preparationDescriptionToMarkdownFromNormalized(
+    normalizedFull.slice(0, revealedLen),
+  )
+
+  return (
+    <div
+      ref={descScrollRef}
+      className={clsx(
+        'chat-prep-step-desc-scroll',
+        memoryTailView && 'chat-prep-step-desc-scroll--memory-tail',
+      )}
+    >
+      <div className="chat-prep-step-md">
+        <ReactMarkdown
+          remarkPlugins={[remarkGfm]}
+          components={prepDescriptionMarkdownComponents}
+        >
+          {md}
+        </ReactMarkdown>
+      </div>
+    </div>
+  )
+}
+
+type PrepItem = NonNullable<Message['preparation_items']>[number]
+
+function prepRowKey(it: PrepItem) {
+  return `${it.code}\t${it.name}`
+}
+
+function resolvePrepItemDescription(it: PrepItem, kbRefDesc: string) {
+  const fromApi = it.description?.trim()
+  const fromRefs =
+    it.code === 'knowledge_retrieval' && !fromApi ? kbRefDesc : ''
+  return (fromApi || fromRefs).trim()
+}
+
+type StepItemStatus = NonNullable<StepsProps['items']>[number]['status']
+
+/** SSE 约定 start/end → 内部 phase；其它 phase 为后端透传字符串 */
+function mapPhaseToStepStatus(phase: string): StepItemStatus {
+  if (phase === 'done') return 'finish'
+  if (phase === 'running') return 'process'
+  if (phase === 'error' || phase === 'failed') return 'error'
+  return 'wait'
+}
+
+export { CHAT_PREPARATION_DEMO_ITEMS } from './preparation-demo-items'
+
+/**
+ * 开发态：URL 带 `?chatPrep=1` 时在会话页固定展示 preparation（无需发消息）。
+ * @param search 传入 `useLocation().search` 以便路由变更时与界面同步
+ */
+export function isChatPreparationDemoEnabled(search?: string): boolean {
+  if (!import.meta.env.DEV) return false
+  const q =
+    search ??
+    (typeof window !== 'undefined' ? window.location.search : '')
+  return new URLSearchParams(q).get('chatPrep') === '1'
+}
+
+export function PreparationSteps({
+  items,
+  referencesKnowledgeItems,
+}: {
+  items: NonNullable<Message['preparation_items']>
+  /** 流式阶段与 knowledge_retrieval 步同屏：无 description 时用引用列表拼副标题 */
+  referencesKnowledgeItems?: Message['references_knowledge_items']
+}) {
+  const { t } = useTranslation()
+
+  const kbRefDesc = React.useMemo(() => {
+    if (!referencesKnowledgeItems || referencesKnowledgeItems.length === 0)
+      return ''
+    return buildKnowledgeRetrievalPrepDescriptionFromRefs(
+      referencesKnowledgeItems,
+      t,
+    )
+  }, [referencesKnowledgeItems, t])
+
+  const prevDescByKeyRef = React.useRef<Record<string, string>>({})
+  const [descRevealComplete, setDescRevealComplete] = React.useState<
+    Record<string, boolean>
+  >({})
+  const [sequentialUnlockIdx, setSequentialUnlockIdx] = React.useState(0)
+
+  /** 前缀 preparation 行 identity 变化或列表变短时串行队列从头来（末尾追加新行不重置） */
+  const prevPrepRowKeysRef = React.useRef<string[]>([])
+
+  React.useLayoutEffect(() => {
+    const keys = items.map(prepRowKey)
+    const prev = prevPrepRowKeysRef.current
+    if (prev.length === 0) {
+      prevPrepRowKeysRef.current = keys
+      return
+    }
+    const minLen = Math.min(prev.length, keys.length)
+    let prefixBroken = false
+    for (let i = 0; i < minLen; i++) {
+      if (prev[i] !== keys[i]) {
+        prefixBroken = true
+        break
+      }
+    }
+    if (prefixBroken || keys.length < prev.length) {
+      setSequentialUnlockIdx(0)
+      setDescRevealComplete({})
+    }
+    prevPrepRowKeysRef.current = keys
+  }, [items])
+
+  /** 当前串行指针落在「无副标题」行时直接跳过 */
+  React.useLayoutEffect(() => {
+    setSequentialUnlockIdx((u) => {
+      let v = u
+      while (
+        v < items.length &&
+        !resolvePrepItemDescription(items[v], kbRefDesc)
+      ) {
+        v += 1
+      }
+      return v
+    })
+  }, [items, kbRefDesc, sequentialUnlockIdx])
+
+  /** 已播完的行副标题视为完成（对勾与后端 phase 对齐用） */
+  React.useLayoutEffect(() => {
+    setDescRevealComplete((prev) => {
+      const next = { ...prev }
+      let changed = false
+      for (let i = 0; i < sequentialUnlockIdx; i++) {
+        const it = items[i]
+        const d = resolvePrepItemDescription(it, kbRefDesc)
+        const k = prepRowKey(it)
+        if (d && next[k] !== true) {
+          next[k] = true
+          changed = true
+        }
+      }
+      return changed ? next : prev
+    })
+  }, [sequentialUnlockIdx, items, kbRefDesc])
+
+  React.useLayoutEffect(() => {
+    setDescRevealComplete((prev) => {
+      const next = { ...prev }
+      let changed = false
+      for (const it of items) {
+        const key = prepRowKey(it)
+        const desc = resolvePrepItemDescription(it, kbRefDesc)
+        const prevD = prevDescByKeyRef.current[key]
+        if (desc !== prevD) {
+          prevDescByKeyRef.current[key] = desc
+          if (desc) {
+            if (next[key] !== false) {
+              next[key] = false
+              changed = true
+            }
+          } else if (key in next) {
+            delete next[key]
+            changed = true
+          }
+        }
+      }
+      return changed ? next : prev
+    })
+  }, [items, kbRefDesc])
+
+  const handleDescRevealStart = React.useCallback((key: string) => {
+    setDescRevealComplete((prev) => {
+      if (prev[key] === false) return prev
+      return { ...prev, [key]: false }
+    })
+  }, [])
+
+  const handleDescRevealComplete = React.useCallback((key: string) => {
+    const idx = items.findIndex((it) => prepRowKey(it) === key)
+    if (idx < 0) return
+    setDescRevealComplete((prev) => {
+      if (prev[key]) return prev
+      return { ...prev, [key]: true }
+    })
+    setSequentialUnlockIdx(idx + 1)
+  }, [items])
+
+  const stepsItems = React.useMemo((): StepsProps['items'] => {
+    return items.map((it: PrepItem, idx: number) => {
+      const title = it.name || it.code
+      const key = prepRowKey(it)
+      const backendStatus = mapPhaseToStepStatus(it.phase)
+      const desc = resolvePrepItemDescription(it, kbRefDesc)
+
+      let displayStatus = backendStatus
+      if (backendStatus === 'error') {
+        displayStatus = 'error'
+      } else if (desc) {
+        if (idx > sequentialUnlockIdx) {
+          displayStatus = 'wait'
+        } else if (idx < sequentialUnlockIdx) {
+          displayStatus = backendStatus
+        } else if (!descRevealComplete[key]) {
+          displayStatus = 'process'
+        } else {
+          displayStatus = backendStatus
+        }
+      }
+
+      const row: NonNullable<StepsProps['items']>[number] = {
+        title,
+        status: displayStatus,
+      }
+
+      if (desc) {
+        if (idx > sequentialUnlockIdx) {
+          /* 未到串行轮次：不渲染副标题 */
+        } else if (idx < sequentialUnlockIdx) {
+          row.description = (
+            <PreparationStepDescriptionMd
+              key={key}
+              rowKey={key}
+              revealMode="full"
+              source={desc}
+              stepCode={it.code}
+            />
+          )
+        } else {
+          row.description = (
+            <PreparationStepDescriptionMd
+              key={key}
+              rowKey={key}
+              revealMode="typing"
+              source={desc}
+              stepCode={it.code}
+              onRevealStart={handleDescRevealStart}
+              onRevealComplete={handleDescRevealComplete}
+            />
+          )
+        }
+      }
+
+      if (displayStatus === 'finish') {
+        row.icon = (
+          <span className="chat-prep-step-icon-inner" aria-hidden>
+            <CheckCircle2 size={18} strokeWidth={2} />
+          </span>
+        )
+      } else if (displayStatus === 'process' || displayStatus === 'wait') {
+        row.icon = (
+          <span
+            className="chat-prep-step-spin"
+            role="status"
+            aria-label={t('common.loading')}
+          >
+            <Spin size="small" />
+          </span>
+        )
+      }
+      return row
+    })
+  }, [
+    items,
+    kbRefDesc,
+    t,
+    descRevealComplete,
+    sequentialUnlockIdx,
+    handleDescRevealStart,
+    handleDescRevealComplete,
+  ])
+
+  if (!items.length) return null
+
+  return (
+    <div className="chat-prep-panel">
+      <div className="chat-prep-heading">{t('chat.preparation_heading')}</div>
+      <div className="chat-prep-steps-wrap">
+        <CxSteps
+          orientation="vertical"
+          size="small"
+          items={stepsItems}
+          className="chat-prep-steps"
+        />
+      </div>
+    </div>
+  )
+}
+
+export default PreparationSteps

package/src/views/chat/components/message-list/suggestion-list.tsx

@@ -0,0 +1,36 @@
+import React from 'react'
+import clsx from 'clsx'
+
+/** 与流式/历史里 `suggested_replies` → `message.options` 同一套样式 */
+const SUGGESTED_REPLY_BTN_CLS = clsx(
+  'w-fit max-w-full',
+  'text-left break-words whitespace-normal',
+  'px-4 py-2.5 rounded-xl text-[13px] leading-relaxed',
+  'text-gray-700 dark:text-gray-200',
+  'bg-[#f2f3f5] dark:bg-[#2d2e30]',
+  'hover:bg-[#e8eaed] dark:hover:bg-[#3a3b3d]',
+  'transition-colors duration-150',
+)
+
+export const SuggestionList: React.FC<{
+  options: string[]
+  keyPrefix: string
+  onOptionClick?: (option: string) => void | Promise<void>
+}> = ({ options, keyPrefix, onOptionClick }) => (
+  <div className="mt-2 flex flex-col gap-2 items-start">
+    {options.map((option, idx) => (
+      <button
+        type="button"
+        key={`${keyPrefix}-${idx}`}
+        onClick={() => {
+          const fn = onOptionClick
+          if (fn) void fn(option)
+        }}
+        className={SUGGESTED_REPLY_BTN_CLS}
+      >
+        {option}
+      </button>
+    ))}
+  </div>
+)
+

package/src/views/chat/components/message-list/thinking-process.tsx

@@ -0,0 +1,49 @@
+import { Spin } from 'antd'
+import React from 'react'
+import { useTranslation } from 'react-i18next'
+
+export const ThinkingProcess: React.FC<{
+  thoughts: string[]
+  isContentVisible: boolean
+}> = ({ thoughts, isContentVisible }) => {
+  const { t } = useTranslation()
+  const currentThought =
+    thoughts && thoughts.length > 0 ? thoughts[thoughts.length - 1] : ''
+
+  const displayThought = React.useMemo(() => {
+    if (!currentThought) return ''
+    let text = currentThought
+    try {
+      if (currentThought.trim().startsWith('{')) {
+        const parsed = JSON.parse(currentThought)
+        text = parsed.thought || parsed.action || parsed.status || currentThought
+      }
+    } catch {
+      // ignore
+    }
+    return text.replace(/\.{3}$|…$/, '')
+  }, [currentThought])
+
+  if (isContentVisible) return null
+  if (!thoughts || thoughts.length === 0) return null
+
+  return (
+    <div className="mb-2">
+      <div className="flex items-center gap-2 text-sm text-gray-500 dark:text-gray-400">
+        <span
+          key={displayThought}
+          className="font-mono animate-fade-in"
+        >
+          {displayThought}
+        </span>
+        <div
+          className="flex h-6 shrink-0 items-center [&_.ant-spin-nested-loading]:!p-0"
+          role="status"
+          aria-label={t('common.loading')}
+        >
+          <Spin size="small" />
+        </div>
+      </div>
+    </div>
+  )
+}