@roaming-ai/dsh-group-chat 0.2.0

package/src/client/GroupChatPanel.tsx

@@ -0,0 +1,385 @@
+/**
+ * 主面板：三区工作台——左导航栏（搜索 + 群组→会话目录树）、中央会话流
+ * （@成员 点名 + markdown 渲染 + 思考折叠）、右上下文栏（群成员角色卡 +
+ * 工作区目录），右栏可收起，角色编辑走右侧滑出抽屉。
+ *
+ * 面板数据走 /api/group-chat/*（fetch + SSE），Host 半持有全部状态。
+ * @module dsh-group-chat/client/panel
+ */
+
+import { useCallback, useEffect, useState, type ReactNode } from 'react'
+import { Icon, P } from './lib/ui.ts'
+import { api } from './lib/api.ts'
+import { RoleDrawer } from './components/RoleDrawer.tsx'
+import { NavPanel } from './components/NavPanel.tsx'
+import { AsidePanel } from './components/AsidePanel.tsx'
+import { ChatPanel } from './components/ChatPanel.tsx'
+import { useGroupChatState, type ActionOk } from './hooks/useGroupChatState.ts'
+import { useComposerEffects, useComposerInput, useMentionChip, useInputKeyboard } from './hooks/useComposer.ts'
+import { useFileSearch } from './hooks/useFileSearch.ts'
+import { useMentionCandidates, useMentionedRoles, useSafeMentionIndex } from './hooks/useMentionState.ts'
+import { draftFromRole, blankDraft, groupById, roleById, sessById, type ClientSnapshot, type ModelsResponse, type SnapshotRole } from './lib/model.ts'
+
+export function GroupChatPanel(): ReactNode {
+  const state = useGroupChatState()
+  const {
+    snap,
+    gid,
+    setGid,
+    sid,
+    setSid,
+    search,
+    setSearch,
+    collapsedGroups,
+    setCollapsedGroups,
+    renameDraft,
+    setRenameDraft,
+    confirmDel,
+    setConfirmDel,
+    confirmClear,
+    setConfirmClear,
+    roleDraft,
+    setRoleDraft,
+    roleFormError,
+    setRoleFormError,
+    models,
+    setModels,
+    modelsError,
+    setModelsError,
+    fileBrowser,
+    setFileBrowser,
+    wsDraft,
+    setWsDraft,
+    partsSel,
+    setPartsSel,
+    rounds,
+    setRounds,
+    input,
+    setInput,
+    err,
+    setErr,
+    topicDraft,
+    setTopicDraft,
+    mention,
+    setMention,
+    mentionIdx,
+    setMentionIdx,
+    asideOpen,
+    setAsideOpen,
+    navOpen,
+    setNavOpen,
+    atBottom,
+    setAtBottom,
+    inputRef,
+    sendingRef,
+    scrollRef,
+    action,
+    mutate,
+  } = state
+
+  // 瞬时通知（toast）：key 为展示序号，同文案重复触发也会重启动画
+  const [toast, setToast] = useState<{ text: string, seq: number } | null>(null)
+
+  // ---- 所有 Hooks 必须在条件返回之前调用 ----
+  // Composer effects
+  const { onMsgsScroll } = useComposerEffects(inputRef, scrollRef, input, atBottom, snap)
+  const { syncFromDOM, onInputCE, onPasteCE, onDragOverCE, onDropCE } = useComposerInput(inputRef, setInput, setMention, setMentionIdx)
+
+  // 选中群组/会话解析（用于 hooks 依赖）
+  let group = snap && gid ? groupById(snap, gid) : null
+  if (!group && snap && snap.groups.length) group = snap.groups[0]
+  let sess = snap && sid ? sessById(snap, sid) : null
+  // 有效会话统一兜底（与渲染体一致）：sid 未建立/未命中/跨群不匹配时取当前群组
+  // 最后一个会话——必须在 busyNow 等 run 派生值之前完成，否则流式行/停止按钮
+  // 在兜底视图（典型：host 重启后 lastCreated 为空、选中态从未建立）下永远失活
+  if ((!sess || sess.groupId !== group?.id) && group && snap) {
+    sess = group.sessionIds.length ? sessById(snap, group.sessionIds[group.sessionIds.length - 1]) : null
+  }
+
+  const enabledRoles = group ? group.roleIds.map((id) => roleById(snap!, id)).filter((r): r is SnapshotRole => !!r && r.enabled) : []
+  const participants = partsSel || enabledRoles.map((r) => r.id)
+  const busyNow = !!(sess && snap && snap.run.running && snap.run.sessionId === sess.id)
+
+  // 查看即清：当前选中会话即 run.finished 所指会话 → 发 ackFinish 确认已读
+  // （host 幂等清除 + 广播；覆盖点击/键盘/重挂恢复/lastCreated 定位全部选中路径）
+  const finishedRun = snap ? snap.run.finished : null
+  useEffect(() => {
+    if (finishedRun && sess && finishedRun.sessionId === sess.id) void mutate({ op: 'ackFinish' })
+  }, [finishedRun, sess])
+
+  // 提及状态：角色候选、文件搜索、索引安全化
+  const mentionCandidates = useMentionCandidates(mention, enabledRoles)
+  const { fileCandidates, fileSearchError, fileSearchLoading } = useFileSearch(
+    mention,
+    group?.id,
+  )
+  const mentionIdxC = useSafeMentionIndex(
+    mentionCandidates.length || fileCandidates.length,
+    mentionIdx
+  )
+  
+  const mentionedRoles = useMentionedRoles(input, enabledRoles)
+
+  const { insertChip, insertFileChip } = useMentionChip(inputRef, setMention, setMentionIdx, syncFromDOM)
+
+  const sendMsg = useCallback(async (): Promise<void> => {
+    if (busyNow || !sess || sendingRef.current) return
+    sendingRef.current = true
+    try {
+      const parts = mentionedRoles.length ? mentionedRoles.map((r) => r.id) : participants
+      if (!parts.length) {
+        setErr(mentionedRoles.length ? '' : '请至少选择一个参与角色（或在消息中 @成员）')
+        if (!mentionedRoles.length) return
+      }
+      const res = await action({ kind: 'send', sessionId: sess.id, text: input, participantRoleIds: parts, rounds }) as ActionOk | null
+      if (res && !res.ok && res.error) setErr(res.error)
+      else if (res && res.ok) {
+        const el = inputRef.current
+        if (el) el.innerHTML = ''
+        setInput('')
+        setMention(null)
+        setErr('')
+        setAtBottom(true)
+        syncFromDOM()
+      }
+    } finally {
+      sendingRef.current = false
+    }
+  }, [busyNow, sess, sendingRef, mentionedRoles, participants, action, rounds, input, inputRef, setInput, setMention, setErr, setAtBottom, syncFromDOM])
+
+  const { onInputKeyDown } = useInputKeyboard(mention, mentionCandidates, mentionIdxC, setMentionIdx, insertChip, insertFileChip, fileCandidates, setMention, sendMsg)
+
+  // ---- 条件性早期返回 ----
+  if (!snap) {
+    return (
+      <div className="dsgc-root">
+        <div className="dsgc-loading">{Icon(P.IconLoadingOutline16, 16)}加载中…</div>
+      </div>
+    )
+  }
+
+  if (!group) {
+    return (
+      <div className="dsgc-root">
+        <div className="dsgc-loading">暂无群组</div>
+      </div>
+    )
+  }
+
+  const msgById: Record<string, ClientSnapshot['messages'][number]> = {}
+  for (const m of snap.messages) msgById[m.id] = m
+
+  const togglePart = (rid: string): void => {
+    const has = participants.includes(rid)
+    setPartsSel(has ? participants.filter((x) => x !== rid) : participants.concat([rid]))
+  }
+
+  // 清空确认：不可清空（对话进行中）走 toast 提示，不再落到输入框上方的红字
+  const doClear = async (): Promise<void> => {
+    if (!sess) return
+    if (busyNow) {
+      setToast({ text: '对话进行中，需先停止才能清空', seq: Date.now() })
+      return
+    }
+    const res = await mutate({ op: 'clearMessages', sessionId: sess.id })
+    if (res && res.ok && res.snapshot && !res.snapshot.error) setConfirmClear(false)
+    else if (res && res.snapshot && res.snapshot.error) {
+      setErr('')
+      setToast({ text: res.snapshot.error, seq: Date.now() })
+    }
+  }
+
+  // ---- 动作 ----
+  const fetchModels = async (): Promise<void> => {
+    try {
+      const m = await api.action({ kind: 'models' }) as ModelsResponse
+      if (m && m.ok && Array.isArray(m.providers)) {
+        setModels(m)
+        setModelsError(null)
+        return
+      }
+      setModelsError(m && m.error ? String(m.error) : '响应异常')
+    } catch (e) {
+      setModelsError(String((e && (e as Error).message) || e))
+    }
+  }
+
+  const openRoleEditor = async (role: SnapshotRole | null): Promise<void> => {
+    setErr('')
+    setRoleFormError('')
+    if (!models || modelsError) await fetchModels()
+    setRoleDraft(role ? draftFromRole(role) : blankDraft())
+  }
+
+  const saveRole = async (): Promise<void> => {
+    if (!roleDraft) return
+    if (!roleDraft.name.trim()) {
+      setRoleFormError('角色名称不能为空')
+      return
+    }
+    if (!roleDraft.provider || !roleDraft.model) {
+      setRoleFormError('请选择角色绑定的模型')
+      return
+    }
+    const res = await mutate({ op: 'upsertRole', groupId: group.id, role: roleDraft })
+    if (res && res.ok && res.snapshot && !res.snapshot.error) {
+      setRoleDraft(null)
+      setRoleFormError('')
+    }
+  }
+
+  const stopRun = async (): Promise<void> => {
+    await action({ kind: 'stop', sessionId: sess!.id })
+  }
+
+  const openBrowser = async (path: string | undefined): Promise<void> => {
+    setFileBrowser({ open: true, loading: true, list: null, error: '' })
+    try {
+      const res = await api.action({ kind: 'browse', path: path || '' }) as import('../core/types.ts').BrowseResult
+      if (res && res.ok) setFileBrowser({ open: true, loading: false, list: res, error: '' })
+      else setFileBrowser({ open: true, loading: false, list: null, error: (res && res.error) || '浏览失败' })
+    } catch (e) {
+      setFileBrowser({ open: true, loading: false, list: null, error: String((e && (e as Error).message) || e) })
+    }
+  }
+
+  const selectCurrentDir = (): void => {
+    if (!fileBrowser || !fileBrowser.list || !group) return
+    const path = fileBrowser.list.path!
+    void mutate({ op: 'setWorkspaceDir', groupId: group.id, path })
+    setWsDraft(null)
+    setFileBrowser(null)
+  }
+
+  return (
+    <div className="dsgc-root">
+      <NavPanel
+        snap={snap}
+        search={search}
+        setSearch={setSearch}
+        collapsedGroups={collapsedGroups}
+        setCollapsedGroups={setCollapsedGroups}
+        gid={group.id}
+        sid={sess ? sess.id : sid}
+        setGid={setGid}
+        setSid={setSid}
+        setPartsSel={setPartsSel}
+        renameDraft={renameDraft}
+        setRenameDraft={setRenameDraft}
+        confirmDel={confirmDel}
+        setConfirmDel={setConfirmDel}
+        mutate={mutate}
+        navOpen={navOpen}
+      />
+      <ChatPanel
+        snap={snap}
+        sess={sess}
+        group={group}
+        enabledRoles={enabledRoles}
+        participants={participants}
+        mentionedRoles={mentionedRoles}
+        busyNow={busyNow}
+        input={input}
+        mention={mention}
+        mentionCandidates={mentionCandidates}
+        mentionIdxC={mentionIdxC}
+        fileCandidates={fileCandidates}
+        fileSearchError={fileSearchError}
+        fileSearchLoading={fileSearchLoading}
+        rounds={rounds}
+        err={err}
+        atBottom={atBottom}
+        topicDraft={topicDraft}
+        msgById={msgById}
+        navOpen={navOpen}
+        asideOpen={asideOpen}
+        inputRef={inputRef}
+        scrollRef={scrollRef}
+        setTopicDraft={setTopicDraft}
+        setConfirmClear={setConfirmClear}
+        setMentionIdx={setMentionIdx}
+        setRounds={setRounds}
+        setNavOpen={setNavOpen}
+        setAsideOpen={setAsideOpen}
+        togglePart={togglePart}
+        onMsgsScroll={() => {
+          const isBottom = onMsgsScroll()
+          if (isBottom !== undefined) setAtBottom(isBottom)
+        }}
+        onInputCE={onInputCE}
+        onInputKeyDown={onInputKeyDown}
+        onPasteCE={onPasteCE}
+        onDropCE={onDropCE}
+        onDragOverCE={onDragOverCE}
+        insertChip={insertChip}
+        insertFileChip={insertFileChip}
+        sendMsg={sendMsg}
+        stopRun={stopRun}
+        action={action}
+        mutate={mutate}
+        setMention={setMention}
+      />
+      <AsidePanel
+        snap={snap}
+        group={group}
+        asideOpen={asideOpen}
+        wsDraft={wsDraft}
+        setWsDraft={setWsDraft}
+        fileBrowser={fileBrowser}
+        setFileBrowser={setFileBrowser}
+        mutate={mutate}
+        openRoleEditor={openRoleEditor}
+        openBrowser={openBrowser}
+        selectCurrentDir={selectCurrentDir}
+      />
+      {sess && confirmClear
+        ? (
+          <P.Modal
+            open
+            onClose={() => { setConfirmClear(false) }}
+            title="清空本会话的消息记录？"
+            closeLabel="关闭"
+            description={'会话「' + sess.name + '」的全部 ' + sess.messageIds.length + ' 条消息将被永久删除'}
+            footer={(
+              <>
+                <P.Button variant="outline" size="sm" onClick={() => { setConfirmClear(false) }}>取消</P.Button>
+                <P.Button variant="outline" size="sm" className="dsgc-stopbtn" onClick={() => { void doClear() }}>清空</P.Button>
+              </>
+            )}
+          >
+            <ul className="dsgc-clearnotes">
+              <li>删除内容：本会话的用户消息与角色发言（含思考、工具调用记录），确认后立即落盘</li>
+              <li>不可恢复：此操作没有回收站，也没有撤销</li>
+              <li>不受影响：会话本身与主题、群成员角色、工作区目录、权限档位</li>
+            </ul>
+          </P.Modal>
+        )
+        : null}
+      {toast
+        ? (
+          <P.Toast
+            key={toast.seq}
+            text={toast.text}
+            icon={Icon(P.IconWarningOutline16, 16)}
+            anchor={inputRef.current}
+            onDone={() => { setToast(null) }}
+          />
+        )
+        : null}
+      {roleDraft
+        ? (
+          <RoleDrawer
+            draft={roleDraft}
+            set={setRoleDraft}
+            models={models}
+            modelsError={modelsError}
+            onRetryModels={() => { void fetchModels() }}
+            onSave={() => { void saveRole() }}
+            onCancel={() => { setRoleDraft(null); setRoleFormError('') }}
+            formError={roleFormError}
+          />
+          )
+        : null}
+    </div>
+  )
+}

package/src/client/components/AsidePanel.tsx

@@ -0,0 +1,188 @@
+/**
+ * 右侧成员与工作区栏组件
+ * @module dsh-group-chat/client/components
+ */
+
+import type { ReactNode } from 'react'
+import { Icon, P } from '../lib/ui.ts'
+import { roleById, type ClientSnapshot, type ModelsResponse, type RoleDraft, type SnapshotRole } from '../lib/model.ts'
+
+interface AsidePanelProps {
+  snap: ClientSnapshot
+  group: ClientSnapshot['groups'][number]
+  asideOpen: boolean
+  wsDraft: string | null
+  setWsDraft: (val: string | null) => void
+  fileBrowser: { open: boolean, loading: boolean, list: import('../../core/types.ts').BrowseResult | null, error: string } | null
+  setFileBrowser: (val: { open: boolean, loading: boolean, list: import('../../core/types.ts').BrowseResult | null, error: string } | null) => void
+  mutate: (args: Record<string, unknown>) => Promise<unknown>
+  openRoleEditor: (role: SnapshotRole | null) => Promise<void>
+  openBrowser: (path: string | undefined) => Promise<void>
+  selectCurrentDir: () => void
+}
+
+export function AsidePanel(props: AsidePanelProps): ReactNode {
+  const { snap, group, asideOpen, wsDraft, setWsDraft, fileBrowser, setFileBrowser, mutate, openRoleEditor, openBrowser, selectCurrentDir } = props
+
+  const commitWsDir = (): void => {
+    if (wsDraft !== null && group && wsDraft !== (group.workspaceDir || '')) {
+      void mutate({ op: 'setWorkspaceDir', groupId: group.id, path: wsDraft })
+    }
+    setWsDraft(null)
+  }
+
+  return (
+    <div className={'dsgc-aside' + (asideOpen ? '' : ' closed')} aria-hidden={asideOpen ? undefined : 'true'}>
+      <div className="dsgc-sec">
+        <div className="dsgc-sechead">
+          群成员
+          <span className="dsgc-secspacer" />
+          <span className="dsgc-seccount">{group.roleIds.length ? group.roleIds.length + ' 个' : ''}</span>
+          <P.Button variant="ghost" size="sm" onClick={() => { void openRoleEditor(null) }} aria-label="添加角色">
+            {Icon(P.IconPlusOutline16, 14)}添加
+          </P.Button>
+        </div>
+        {group.roleIds.length
+          ? (
+            <div className="dsgc-roles">
+              {group.roleIds.map((rid) => {
+                const r = roleById(snap, rid)
+                if (!r) return null
+                return (
+                  <div
+                    key={r.id}
+                    className={'dsgc-role' + (r.enabled ? '' : ' off')}
+                    role="button"
+                    tabIndex={0}
+                    onClick={() => { void openRoleEditor(r) }}
+                    onKeyDown={(e) => { if (e.key === 'Enter') { e.preventDefault(); void openRoleEditor(r) } }}
+                    title="点击编辑角色"
+                  >
+                    <div className="dsgc-rolehead">
+                      <span className="dsgc-roledot" style={{ background: r.color || '#888' }} />
+                      <span className="dsgc-rolename">{r.name}</span>
+                      <P.Tooltip label={r.enabled ? '停用该角色' : '启用该角色'} side="top" delayMs={300}>
+                        <span
+                          onClick={(e) => { e.stopPropagation() }}
+                          onKeyDown={(e) => { e.stopPropagation() }}
+                          style={{ display: 'inline-flex', flex: 'none' }}
+                        >
+                          <P.Switch
+                            checked={r.enabled}
+                            onChange={() => { void mutate({ op: 'setRoleEnabled', roleId: r.id, enabled: !r.enabled }) }}
+                            label={r.enabled ? '停用该角色' : '启用该角色'}
+                            aria-label={(r.enabled ? '停用' : '启用') + '角色 ' + r.name}
+                          />
+                        </span>
+                      </P.Tooltip>
+                    </div>
+                    {r.persona ? <div className="dsgc-rolepersona" title={r.persona}>{r.persona}</div> : null}
+                    <div className="dsgc-rolemenu">
+                      <span
+                        className="dsgc-rolemodel"
+                        title={r.provider + ' / ' + r.model + (r.thinking ? ' · 深度思考' + (r.reasoningEffort && r.reasoningEffort !== 'default' ? '（' + r.reasoningEffort + '）' : '') : '')}
+                      >
+                        {r.provider} / {r.model}
+                      </span>
+                      {r.thinking
+                        ? <span title="深度思考" style={{ display: 'inline-flex', alignItems: 'center', color: 'var(--dsw-alias-label-tertiary,inherit)' }}>{Icon(P.IconThinkOutline14, 14)}</span>
+                        : null}
+                      <span className="dsgc-roleops">
+                        <button
+                          className="dsgc-opbtn"
+                          title="编辑角色"
+                          aria-label="编辑角色"
+                          onClick={(e) => { e.stopPropagation(); void openRoleEditor(r) }}
+                        >
+                          {Icon(P.IconEditOutline16, 14)}
+                        </button>
+                        <button
+                          className="dsgc-opbtn danger"
+                          title="移除角色"
+                          aria-label="移除角色"
+                          onClick={(e) => { e.stopPropagation(); void mutate({ op: 'deleteRole', roleId: r.id }) }}
+                        >
+                          {Icon(P.IconTrashOutline16, 14)}
+                        </button>
+                      </span>
+                    </div>
+                  </div>
+                )
+              })}
+            </div>
+            )
+          : <div className="dsgc-hint">还没有角色。每个角色可绑定不同的 provider/model，在群内以独立身份发言。</div>}
+      </div>
+      <div className="dsgc-sec">
+        <div className="dsgc-sechead">工作区目录</div>
+        <div className="dsgc-field">
+          <div className="dsgc-wsrow">
+            <input
+              className="dsgc-input"
+              value={wsDraft === null ? (group.workspaceDir || '') : wsDraft}
+              placeholder="~/docs 或 /abs/dir"
+              onChange={(e) => { setWsDraft(e.target.value) }}
+              onBlur={commitWsDir}
+              onKeyDown={(e) => { if (e.key === 'Enter') (e.target as HTMLInputElement).blur() }}
+            />
+            <P.Button variant="outline" size="sm" onClick={() => { void openBrowser(wsDraft === null ? group.workspaceDir : wsDraft) }}>
+              {Icon(P.IconFolderOpenOutline16, 14)}浏览
+            </P.Button>
+          </div>
+          <div className="dsgc-hint">发送时读取目录内文本文件，注入本群全体角色上下文；角色也可用工具主动查看</div>
+          {group.workspaceDir === '~' || group.workspaceDir === '/'
+            ? <div className="dsgc-err">工作区指向整个主目录/根目录：角色的只读工具将可读取该范围下的所有文件，请谨慎</div>
+            : null}
+        </div>
+        {fileBrowser && fileBrowser.open
+          ? (
+            <div className="dsgc-fb">
+              <div className="dsgc-fbhead">
+                <span className="dsgc-fbpath" title={fileBrowser.list ? fileBrowser.list.path : ''}>
+                  {fileBrowser.loading ? '读取中…' : (fileBrowser.list ? fileBrowser.list.path : '')}
+                </span>
+                <span style={{ display: 'flex', gap: 4, alignItems: 'center' }}>
+                  <P.Button variant="primary" size="sm" disabled={!fileBrowser.list} onClick={selectCurrentDir}>选定此目录</P.Button>
+                  {fileBrowser.list
+                    ? <P.Button variant="outline" size="sm" title="上一级" aria-label="上一级" onClick={() => { void openBrowser(fileBrowser.list!.parent) }}>{Icon(P.IconChevronUpOutline14, 14)}</P.Button>
+                    : null}
+                  {fileBrowser.list
+                    ? <P.Button variant="outline" size="sm" title="主目录" aria-label="主目录" onClick={() => { void openBrowser(fileBrowser.list!.home) }}>{Icon(P.IconFolderClose16, 14)}</P.Button>
+                    : null}
+                  <P.Button variant="ghost" size="sm" onClick={() => { setFileBrowser(null) }} aria-label="关闭浏览器">{Icon(P.IconCloseOutline16, 14)}</P.Button>
+                </span>
+              </div>
+              {fileBrowser.error ? <div className="dsgc-err">{fileBrowser.error}</div> : null}
+              {fileBrowser.list
+                ? (
+                  <div className="dsgc-fblist">
+                    {(fileBrowser.list.entries || []).length
+                      ? (fileBrowser.list.entries || []).map((e) => e.type === 'directory'
+                        ? (
+                          <button
+                            key={e.path}
+                            type="button"
+                            className={'dsgc-fbrow' + (e.hidden ? ' dim' : '') + ' dir'}
+                            onClick={() => { void openBrowser(e.path) }}
+                          >
+                            {Icon(e.hidden ? P.IconFolderClose16 : P.IconFolderOpenOutline16, 14)}
+                            <span className="dsgc-fbname">{e.name}/</span>
+                          </button>
+                          )
+                        : (
+                          <div key={e.path} className="dsgc-fbrow dim file">
+                            <span className="dsgc-fbname">{e.name}</span>
+                            {e.size !== undefined ? <span className="dsgc-fbsize">{(P as unknown as { fileSizeText: (n: number) => string }).fileSizeText(e.size)}</span> : null}
+                          </div>
+                          ))
+                      : <div className="dsgc-hint">空目录</div>}
+                  </div>
+                  )
+                : null}
+            </div>
+            )
+          : null}
+      </div>
+    </div>
+  )
+}

package/src/client/components/Bubble.tsx

@@ -0,0 +1,76 @@
+/**
+ * 聊天消息气泡（user / system / 角色发言）。
+ *
+ * 帧稳定 memo：SSE 全量快照（~65KB × 7fps）每帧重建全部消息对象 identity，
+ * 但已完成消息在 host 侧 append 后不可变——按渲染相关字段做值比较，流式
+ * 期间跳过已完成消息的重渲（每帧仅 live 行与派生列表变化），避免全量
+ * MarkdownText 重新解析打满主线程导致「卡死后一次性蹦出」。
+ * @module dsh-group-chat/client/Bubble
+ */
+
+import { memo, type ReactNode } from 'react'
+import { P } from '../lib/ui.ts'
+import { fmtTime, MD_LABELS, type ClientSnapshot, type SnapshotRole } from '../lib/model.ts'
+import { ThinkRow } from './ThinkRow.tsx'
+import { ToolRow } from './ToolRow.tsx'
+
+export interface BubbleProps {
+  m: ClientSnapshot['messages'][number]
+  /** 父级解析好的发言角色（user/system 消息为 null）——避免 Bubble 依赖 snap identity。 */
+  role: SnapshotRole | null
+}
+
+function BubbleInner({ m, role }: BubbleProps): ReactNode {
+  const isUser = m.speaker === 'user'
+  const isSys = m.speaker === 'system'
+  const name = isUser ? '我' : isSys ? '系统' : role ? role.name : '成员'
+  if (isSys) return <div className={'dsgc-sysmsg' + (m.error ? ' err' : '')}>{m.text}</div>
+  return (
+    <div className={'dsgc-msg' + (isUser ? ' mine' : '')}>
+      <div
+        className={'dsgc-avatar' + (isUser ? ' mine' : '')}
+        style={isUser || !role ? undefined : { border: '2px solid ' + (role.color || '#888') }}
+      >
+        {name.slice(0, 1)}
+      </div>
+      <div className="dsgc-msgbody">
+        <div className="dsgc-msghead">
+          <span className="dsgc-msgname">{name}</span>
+          {m.model ? <span className="dsgc-msgmodel" title={m.model}>{m.model}</span> : null}
+          {m.ts ? <span className="dsgc-msgtime">{fmtTime(m.ts)}</span> : null}
+        </div>
+        {isUser
+          ? <div className="dsgc-msgtext">{m.text}</div>
+          : (
+            <div className="dsgc-msgtext">
+              {m.reasoning ? <ThinkRow text={m.reasoning} /> : null}
+              {(Array.isArray(m.toolCalls) ? m.toolCalls : []).map((c, i) => <ToolRow key={'tc' + i} c={c} />)}
+              <P.MarkdownText text={m.text || '（无内容）'} labels={MD_LABELS} />
+            </div>
+            )}
+      </div>
+    </div>
+  )
+}
+
+/** 渲染相关字段的值比较（消息不可变；角色仅名/色参与渲染）。 */
+function bubblePropsEqual(a: BubbleProps, b: BubbleProps): boolean {
+  const x = a.m
+  const y = b.m
+  if (x !== y) {
+    if (x.id !== y.id || x.speaker !== y.speaker || x.text !== y.text || x.reasoning !== y.reasoning || x.model !== y.model || x.error !== y.error || x.ts !== y.ts) return false
+    const ta = Array.isArray(x.toolCalls) ? x.toolCalls : []
+    const tb = Array.isArray(y.toolCalls) ? y.toolCalls : []
+    if (ta.length !== tb.length) return false
+    for (let i = 0; i < ta.length; i++) {
+      const ca = ta[i]
+      const cb = tb[i]
+      if (ca !== cb && (ca.tool !== cb.tool || ca.status !== cb.status || ca.output !== cb.output || ca.durationMs !== cb.durationMs || JSON.stringify(ca.args) !== JSON.stringify(cb.args))) return false
+    }
+  }
+  const ra = a.role
+  const rb = b.role
+  return (ra ? ra.name + '\u0000' + (ra.color || '') : '') === (rb ? rb.name + '\u0000' + (rb.color || '') : '')
+}
+
+export const Bubble = memo(BubbleInner, bubblePropsEqual)