@roaming-ai/dsh-group-chat 0.2.0

package/src/client/components/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 组件统一导出
+ * @module dsh-group-chat/client/components
+ */
+
+export * from './NavPanel.tsx'
+export * from './AsidePanel.tsx'
+export * from './ChatPanel.tsx'
+export * from './Composer.tsx'
+export * from './MessageFlow.tsx'

package/src/client/hooks/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Hooks 统一导出
+ * @module dsh-group-chat/client/hooks
+ */
+
+export * from './useGroupChatState.ts'
+export * from './useComposer.ts'

package/src/client/hooks/useComposer.ts

@@ -0,0 +1,272 @@
+/**
+ * 消息输入相关 hooks
+ * @module dsh-group-chat/client/hooks
+ */
+
+import { useCallback, useEffect, type ClipboardEvent as ReactClipboardEvent, type DragEvent as ReactDragEvent, type KeyboardEvent as ReactKeyboardEvent } from 'react'
+import { execCommand, queryAtCaret, serializeInput, chipHtml, fileChipHtml } from '../utils/utils.ts'
+import type { AtToken } from '../../shared/file-mention-grammar.ts'
+import type { SnapshotRole } from '../lib/model.ts'
+
+export function useComposerEffects(
+  inputRef: React.RefObject<HTMLDivElement>,
+  scrollRef: React.RefObject<HTMLDivElement>,
+  input: string,
+  atBottom: boolean,
+  snap: unknown,
+) {
+  // 贴底时新内容自动跟随滚动
+  const onMsgsScroll = useCallback(() => {
+    const el = scrollRef.current
+    if (!el) return
+    const isAtBottom = el.scrollHeight - el.scrollTop - el.clientHeight < 60
+    return isAtBottom
+  }, [scrollRef])
+
+  useEffect(() => {
+    const el = scrollRef.current
+    if (el && atBottom) el.scrollTop = el.scrollHeight
+  }, [snap, atBottom, scrollRef])
+
+  // composer 输入框随内容自适应高度
+  useEffect(() => {
+    const el = inputRef.current
+    if (!el) return
+    el.style.height = 'auto'
+    el.style.height = Math.min(180, Math.max(36, el.scrollHeight)) + 'px'
+  }, [input, inputRef])
+
+  return { onMsgsScroll }
+}
+
+export function useComposerInput(
+  inputRef: React.RefObject<HTMLDivElement>,
+  setInput: (val: string) => void,
+  setMention: (val: AtToken | null) => void,
+  setMentionIdx: (val: number) => void,
+) {
+  /** 从 DOM 同步 input 状态（序列化） */
+  const syncFromDOM = useCallback((): void => {
+    const el = inputRef.current
+    if (!el) return
+    setInput(serializeInput(el))
+  }, [inputRef, setInput])
+
+  const onInputCE = useCallback((): void => {
+    syncFromDOM()
+    setMention(queryAtCaret())
+    setMentionIdx(0)
+  }, [syncFromDOM, setMention, setMentionIdx])
+
+  /** 粘贴/拖放强制纯文本 */
+  const onPasteCE = useCallback((e: ReactClipboardEvent<HTMLDivElement>): void => {
+    e.preventDefault()
+    const text = e.clipboardData.getData('text/plain')
+    if (text) execCommand('insertText', text)
+  }, [])
+
+  const onDragOverCE = useCallback((e: ReactDragEvent<HTMLDivElement>): void => {
+    e.preventDefault()
+  }, [])
+
+  const onDropCE = useCallback((e: ReactDragEvent<HTMLDivElement>): void => {
+    e.preventDefault()
+    const text = e.dataTransfer.getData('text/plain')
+    if (text) execCommand('insertText', text)
+  }, [])
+
+  return {
+    syncFromDOM,
+    onInputCE,
+    onPasteCE,
+    onDragOverCE,
+    onDropCE,
+  }
+}
+
+export function useMentionChip(
+  inputRef: React.RefObject<HTMLDivElement>,
+  setMention: (val: AtToken | null) => void,
+  setMentionIdx: (val: number) => void,
+  syncFromDOM: () => void,
+) {
+  /** 弹层候选 → 删掉光标前的 @词、插入原子芯片 + 尾随空格 */
+  const insertChip = useCallback((role: SnapshotRole): void => {
+    const el = inputRef.current
+    const sel = window.getSelection()
+    if (!el || !sel) return
+    if (!sel.anchorNode || !el.contains(sel.anchorNode)) return
+    el.focus({ preventScroll: true })
+    
+    // 1. 删除光标前的 @token（包括引号）
+    const node = sel.anchorNode
+    if (node.nodeType === Node.TEXT_NODE) {
+      const text = node.nodeValue || ''
+      const off = sel.anchorOffset
+      const before = text.slice(0, off)
+      // 匹配 @词 或 @"词
+      const m = /(?:^|\s)@("?)([^"\s@]*)$/.exec(before)
+      if (m) {
+        const prefixLen = m[1] ? 2 : 1  // @" 或 @
+        const queryLen = m[2].length
+        const start = off - prefixLen - queryLen
+        if (start >= 0) {
+          const range = document.createRange()
+          range.setStart(node, start)
+          range.setEnd(node, off)
+          sel.removeAllRanges()
+          sel.addRange(range)
+          execCommand('delete')
+        }
+      }
+    }
+    
+    // 2. 插入芯片
+    execCommand('insertHTML', chipHtml(role).replace('class="dsgc-chipin"', 'class="dsgc-chipin" data-new=""'))
+    const chip = el.querySelector<HTMLElement>('.dsgc-chipin[data-new]')
+    if (!chip) return
+    
+    // 3. 选区显式钉到芯片之后，再补尾随空格
+    const after = document.createRange()
+    after.setStartAfter(chip)
+    after.collapse(true)
+    sel.removeAllRanges()
+    sel.addRange(after)
+    execCommand('insertText', ' ')
+    chip.removeAttribute('data-new')
+    setMention(null)
+    setMentionIdx(0)
+    syncFromDOM()
+  }, [inputRef, setMention, setMentionIdx, syncFromDOM])
+
+  const insertFileChip = useCallback((path: string, kind: 'file' | 'directory'): void => {
+    const el = inputRef.current
+    const sel = window.getSelection()
+    if (!el || !sel) return
+    if (!sel.anchorNode || !el.contains(sel.anchorNode)) return
+    el.focus({ preventScroll: true })
+    
+    // 1. 删除光标前的 @token（包括引号）
+    const node = sel.anchorNode
+    if (node.nodeType === Node.TEXT_NODE) {
+      const text = node.nodeValue || ''
+      const off = sel.anchorOffset
+      const before = text.slice(0, off)
+      // 匹配 @词 或 @"词
+      const m = /(?:^|\s)@("?)([^"\s@]*)$/.exec(before)
+      if (m) {
+        const prefixLen = m[1] ? 2 : 1  // @" 或 @
+        const queryLen = m[2].length
+        const start = off - prefixLen - queryLen
+        if (start >= 0) {
+          const range = document.createRange()
+          range.setStart(node, start)
+          range.setEnd(node, off)
+          sel.removeAllRanges()
+          sel.addRange(range)
+          execCommand('delete')
+        }
+      }
+    }
+    
+    // 2. 插入文件芯片
+    execCommand('insertHTML', fileChipHtml(path, kind).replace('class="dsgc-chipin dsgc-chipin-file"', 'class="dsgc-chipin dsgc-chipin-file" data-new=""'))
+    const chip = el.querySelector<HTMLElement>('.dsgc-chipin[data-new]')
+    if (!chip) return
+    
+    // 3. 选区显式钉到芯片之后，再补尾随空格
+    const after = document.createRange()
+    after.setStartAfter(chip)
+    after.collapse(true)
+    sel.removeAllRanges()
+    sel.addRange(after)
+    execCommand('insertText', ' ')
+    chip.removeAttribute('data-new')
+    setMention(null)
+    setMentionIdx(0)
+    syncFromDOM()
+  }, [inputRef, setMention, setMentionIdx, syncFromDOM])
+
+  return { insertChip, insertFileChip }
+}
+
+export function useInputKeyboard(
+  mention: AtToken | null,
+  mentionCandidates: SnapshotRole[],
+  mentionIdxC: number,
+  setMentionIdx: (val: number | ((prev: number) => number)) => void,
+  insertChip: (role: SnapshotRole) => void,
+  insertFileChip: (path: string, kind: 'file' | 'directory') => void,
+  fileCandidates: Array<{ path: string; isDir: boolean }>,
+  setMention: (val: AtToken | null) => void,
+  sendMsg: () => Promise<void>,
+) {
+  const onInputKeyDown = useCallback((e: ReactKeyboardEvent<HTMLDivElement>): void => {
+    // IME 组合中的按键不参与任何快捷逻辑
+    if (e.nativeEvent.isComposing || e.keyCode === 229) return
+    
+    // 角色模式（裸 @）：Enter/Tab 插入角色芯片
+    if (mention !== null && mention.query === '' && mentionCandidates.length) {
+      if (e.key === 'ArrowDown') {
+        e.preventDefault()
+        setMentionIdx((mentionIdxC + 1) % mentionCandidates.length)
+        return
+      }
+      if (e.key === 'ArrowUp') {
+        e.preventDefault()
+        setMentionIdx((mentionIdxC - 1 + mentionCandidates.length) % mentionCandidates.length)
+        return
+      }
+      if ((e.key === 'Enter' && !e.shiftKey) || e.key === 'Tab') {
+        e.preventDefault()
+        insertChip(mentionCandidates[mentionIdxC])
+        return
+      }
+    }
+    
+    // 文件模式（@ + query）：Enter 插入文件/Tab 钻入目录/Esc 关闭
+    if (mention !== null && mention.query !== '' && fileCandidates.length) {
+      if (e.key === 'ArrowDown') {
+        e.preventDefault()
+        setMentionIdx((mentionIdxC + 1) % fileCandidates.length)
+        return
+      }
+      if (e.key === 'ArrowUp') {
+        e.preventDefault()
+        setMentionIdx((mentionIdxC - 1 + fileCandidates.length) % fileCandidates.length)
+        return
+      }
+      const selectedItem = fileCandidates[mentionIdxC]
+      if (selectedItem) {
+        if (e.key === 'Enter' && !e.shiftKey) {
+          e.preventDefault()
+          insertFileChip(selectedItem.path, selectedItem.isDir ? 'directory' : 'file')
+          return
+        }
+        if (e.key === 'Tab' && selectedItem.isDir) {
+          e.preventDefault()
+          insertFileChip(selectedItem.path, 'directory')
+          return
+        }
+      }
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        setMention(null)
+        return
+      }
+    }
+    
+    if (e.key === 'Enter' && e.shiftKey) {
+      e.preventDefault()
+      execCommand('insertLineBreak')
+      return
+    }
+    
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault()
+      void sendMsg()
+    }
+  }, [mention, mentionCandidates, mentionIdxC, fileCandidates, setMentionIdx, insertChip, insertFileChip, setMention, sendMsg])
+
+  return { onInputKeyDown }
+}

package/src/client/hooks/useFileSearch.ts

@@ -0,0 +1,115 @@
+/**
+ * 文件搜索 hook：防抖 + 取消过期请求 + 短缓存。
+ * @module dsh-group-chat/client/hooks
+ */
+
+import { useEffect, useState } from 'react'
+import { api } from '../lib/api.ts'
+import type { AtToken } from '../../shared/file-mention-grammar.ts'
+
+export interface FileCandidate {
+  path: string
+  isDir: boolean
+}
+
+export interface FileSearchResult {
+  fileCandidates: FileCandidate[]
+  fileSearchError: string | null
+  fileSearchLoading: boolean
+}
+
+const DEBOUNCE_MS = 180
+const CACHE_LIMIT = 20
+const cache = new Map<string, FileCandidate[]>()
+
+function cacheGet(key: string): FileCandidate[] | undefined {
+  const hit = cache.get(key)
+  if (!hit) return undefined
+  cache.delete(key)
+  cache.set(key, hit)
+  return hit
+}
+
+function cacheSet(key: string, value: FileCandidate[]): void {
+  cache.delete(key)
+  cache.set(key, value)
+  if (cache.size > CACHE_LIMIT) {
+    const oldest = cache.keys().next().value
+    if (oldest !== undefined) cache.delete(oldest)
+  }
+}
+
+function isAbort(err: unknown): boolean {
+  return !!err && typeof err === 'object' && 'name' in err && (err as { name: string }).name === 'AbortError'
+}
+
+/**
+ * 文件搜索：query 变化 180ms 内合并；过期 fetch 真正 abort；
+ * 命中短缓存立刻出结果。离开文件模式才清空列表，避免每个按键闪「检索中」。
+ */
+export function useFileSearch(
+  mention: AtToken | null,
+  groupId: string | undefined,
+): FileSearchResult {
+  const [fileCandidates, setFileCandidates] = useState<FileCandidate[]>([])
+  const [fileSearchError, setFileSearchError] = useState<string | null>(null)
+  const [fileSearchLoading, setFileSearchLoading] = useState(false)
+
+  const query = mention && mention.query !== '' ? mention.query : null
+
+  useEffect(() => {
+    if (query === null || !groupId) {
+      setFileCandidates([])
+      setFileSearchError(null)
+      setFileSearchLoading(false)
+      return
+    }
+
+    const key = groupId + '\0' + query
+    const hit = cacheGet(key)
+    if (hit) {
+      setFileCandidates(hit)
+      setFileSearchError(null)
+      setFileSearchLoading(false)
+      return
+    }
+
+    const controller = new AbortController()
+    setFileSearchLoading(true)
+    const timer = window.setTimeout(() => {
+      void (async () => {
+        try {
+          const res = await api.action({
+            kind: 'fileSearch',
+            groupId,
+            query,
+          }, controller.signal) as { ok: true, candidates?: FileCandidate[] } | { ok: false, error?: string }
+
+          if (controller.signal.aborted) return
+          if (res.ok) {
+            const next = res.candidates || []
+            cacheSet(key, next)
+            setFileCandidates(next)
+            setFileSearchError(null)
+          } else {
+            setFileCandidates([])
+            setFileSearchError(res.error || '文件检索失败')
+          }
+        } catch (err) {
+          if (controller.signal.aborted || isAbort(err)) return
+          setFileCandidates([])
+          setFileSearchError(String(err))
+        } finally {
+          if (!controller.signal.aborted) setFileSearchLoading(false)
+        }
+      })()
+    }, DEBOUNCE_MS)
+
+    return () => {
+      window.clearTimeout(timer)
+      controller.abort()
+    }
+  }, [query, groupId])
+
+  return { fileCandidates, fileSearchError, fileSearchLoading }
+}

package/src/client/hooks/useGroupChatState.ts

@@ -0,0 +1,214 @@
+/**
+ * 群聊面板核心状态管理 hook
+ * @module dsh-group-chat/client/hooks
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { api } from '../lib/api.ts'
+import type { ClientSnapshot, ModelsResponse, RoleDraft } from '../lib/model.ts'
+import type { AtToken } from '../../shared/file-mention-grammar.ts'
+
+export interface MutateResponse {
+  ok: boolean
+  snapshot?: ClientSnapshot
+  lastCreated?: ClientSnapshot['lastCreated']
+  error?: string
+}
+
+export interface ActionOk {
+  ok: boolean
+  error?: string
+}
+
+/**
+ * 面板切换缓存（模块级，跨挂载存活）：main 为 keyed 槽，主会话⇄群聊切换会
+ * 整体卸载重挂面板组件；缓存最近快照与选中项让重挂载瞬时恢复上次视图，
+ * 挂载后的 state 拉取 / SSE 首帧再行校正（本机回路往返仅数毫秒）。
+ */
+let cachedSnap: ClientSnapshot | null = null
+let cachedGid: string | null = null
+let cachedSid: string | null = null
+
+export function useGroupChatState() {
+  // 核心数据快照（重挂载时从缓存瞬时恢复，消除切换闪现的加载态）
+  const [snap, setSnap] = useState<ClientSnapshot | null>(() => cachedSnap)
+
+  // 选中状态
+  const [gid, setGid] = useState<string | null>(() => cachedGid)
+  const [sid, setSid] = useState<string | null>(() => cachedSid)
+
+  /** 已应用过的 lastCreated 会话标记：只在标记变化（真正的新建）时跟随选中，
+      而不是每帧都把视图拽回「最近创建的会话」（流式期间每 120ms 一帧）。 */
+  const appliedCreatedRef = useRef<string | null>(cachedSnap?.lastCreated?.sessionId ?? null)
+
+  /** 快照落地统一口：写状态 + 写切换缓存。 */
+  const applySnap = useCallback((s: ClientSnapshot): void => {
+    cachedSnap = s
+    setSnap(s)
+  }, [])
+
+  /** 选中项统一口：写状态 + 写切换缓存（重挂载恢复到用户离开时的位置）。 */
+  const selectGroup = useCallback((v: string): void => {
+    cachedGid = v
+    setGid(v)
+  }, [])
+  const selectSession = useCallback((v: string): void => {
+    cachedSid = v
+    setSid(v)
+  }, [])
+  
+  // UI 状态
+  const [search, setSearch] = useState('')
+  const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(() => new Set())
+  const [asideOpen, setAsideOpen] = useState(true)
+  const [navOpen, setNavOpen] = useState(true)
+  const [atBottom, setAtBottom] = useState(true)
+  
+  // 编辑态
+  const [renameDraft, setRenameDraft] = useState<{ kind: 'group' | 'session', id: string, value: string } | null>(null)
+  const [confirmDel, setConfirmDel] = useState<{ kind: 'group' | 'session', id: string } | null>(null)
+  const [confirmClear, setConfirmClear] = useState(false)
+  const [topicDraft, setTopicDraft] = useState<string | null>(null)
+  const [wsDraft, setWsDraft] = useState<string | null>(null)
+  
+  // 角色编辑
+  const [roleDraft, setRoleDraft] = useState<RoleDraft | null>(null)
+  const [roleFormError, setRoleFormError] = useState('')
+  const [models, setModels] = useState<ModelsResponse | null>(null)
+  const [modelsError, setModelsError] = useState<string | null>(null)
+  
+  // 文件浏览器
+  const [fileBrowser, setFileBrowser] = useState<{ open: boolean, loading: boolean, list: import('../../core/types.ts').BrowseResult | null, error: string } | null>(null)
+  
+  // 参与角色选择
+  const [partsSel, setPartsSel] = useState<string[] | null>(null)
+  const [rounds, setRounds] = useState(1)
+  
+  // 输入与 @提及
+  const [input, setInput] = useState('')
+  const [mention, setMention] = useState<AtToken | null>(null)
+  const [mentionIdx, setMentionIdx] = useState(0)
+  
+  // 错误提示
+  const [err, setErr] = useState('')
+  
+  // Refs
+  const inputRef = useRef<HTMLDivElement | null>(null)
+  const sendingRef = useRef(false)
+  const scrollRef = useRef<HTMLDivElement | null>(null)
+
+  // 初始加载 + SSE 订阅
+  useEffect(() => {
+    let live = true
+    api.state().then((s) => {
+      if (live && s && (s as ClientSnapshot).ok) applySnap(s as ClientSnapshot)
+    }).catch(() => { /* SSE 会重试 */ })
+    const events = new EventSource('/api/group-chat/events')
+    events.onmessage = (message) => {
+      try {
+        const s = JSON.parse(message.data) as ClientSnapshot
+        if (!live || !s || !s.ok) return
+        // lastCreated 仅在变化时跟随选中（新建群组/会话的定位信号）；
+        // 帧里重复携带的旧标记不再反复重置视图
+        if (s.lastCreated && s.lastCreated.sessionId && s.lastCreated.sessionId !== appliedCreatedRef.current) {
+          appliedCreatedRef.current = s.lastCreated.sessionId
+          selectGroup(s.lastCreated.groupId)
+          selectSession(s.lastCreated.sessionId)
+          setPartsSel(null)
+        }
+        applySnap(s)
+      } catch { /* ignore malformed frame */ }
+    }
+    return () => {
+      live = false
+      events.close()
+    }
+  }, [applySnap, selectGroup, selectSession])
+
+  // API 操作封装
+  const action = useCallback(async (payload: Record<string, unknown>): Promise<unknown> => {
+    try {
+      return await api.action(payload)
+    } catch (e) {
+      setErr(String((e && (e as Error).message) || e))
+      return null
+    }
+  }, [])
+
+  const mutate = async (args: Record<string, unknown>): Promise<MutateResponse | null> => {
+    setErr('')
+    const res = await action(Object.assign({ kind: 'mutate' }, args)) as MutateResponse | null
+    if (res && res.ok && res.snapshot) {
+      // 响应里的 lastCreated 是服务端当前值（未必由本次调用产生）——同样只在
+      // 变化时跟随选中，避免改名/改配置等普通 mutate 把视图拽走
+      if (res.lastCreated && res.lastCreated.sessionId && res.lastCreated.sessionId !== appliedCreatedRef.current) {
+        appliedCreatedRef.current = res.lastCreated.sessionId
+        selectGroup(res.lastCreated.groupId)
+        selectSession(res.lastCreated.sessionId)
+        setPartsSel(null)
+      }
+      applySnap(res.snapshot)
+      if (res.snapshot.error) setErr(res.snapshot.error)
+    }
+    return res
+  }
+
+  return {
+    // 状态
+    snap,
+    setSnap: applySnap,
+    gid,
+    setGid: selectGroup,
+    sid,
+    setSid: selectSession,
+    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,
+    // Refs
+    inputRef,
+    sendingRef,
+    scrollRef,
+    // 方法
+    action,
+    mutate,
+  }
+}

package/src/client/hooks/useMentionState.ts

@@ -0,0 +1,56 @@
+/**
+ * 提及状态 hook：封装角色/文件提及相关的派生状态计算
+ * @module dsh-group-chat/client/hooks
+ */
+
+import { useMemo } from 'react'
+import { escapeRegExp, type SnapshotRole } from '../lib/model.ts'
+import type { AtToken } from '../../shared/file-mention-grammar.ts'
+
+/**
+ * 计算角色提及候选列表
+ * @param mention - 当前 @ token 状态
+ * @param enabledRoles - 启用的角色列表
+ * @returns 角色候选列表（仅在角色模式且 query 为空时返回）
+ */
+export function useMentionCandidates(
+  mention: AtToken | null,
+  enabledRoles: SnapshotRole[],
+): SnapshotRole[] {
+  return useMemo(() => {
+    // 角色模式：仅当 mention 存在且 query 为空时显示全部启用角色
+    return mention !== null && mention.query === '' ? enabledRoles : []
+  }, [mention, enabledRoles])
+}
+
+/**
+ * 检测输入文本中被 @ 的角色
+ * @param input - 输入文本
+ * @param enabledRoles - 启用的角色列表
+ * @returns 被提及的角色列表
+ */
+export function useMentionedRoles(
+  input: string,
+  enabledRoles: SnapshotRole[],
+): SnapshotRole[] {
+  return useMemo(() => {
+    return enabledRoles.filter((r) =>
+      new RegExp('(^|\\s)@' + escapeRegExp(r.name) + '(?=\\s|$)').test(input)
+    )
+  }, [input, enabledRoles])
+}
+
+/**
+ * 计算安全的候选索引（确保不越界）
+ * @param candidatesLength - 候选列表长度
+ * @param currentIndex - 当前索引
+ * @returns 安全的索引值
+ */
+export function useSafeMentionIndex(
+  candidatesLength: number,
+  currentIndex: number,
+): number {
+  return useMemo(() => {
+    return candidatesLength ? Math.min(currentIndex, candidatesLength - 1) : 0
+  }, [candidatesLength, currentIndex])
+}