@huyooo/ai-chat-frontend-react

AI Chat 前端组件库 - React 版本。

📖 深入了解：查看 技术架构文档 了解流式渲染、Content Parts 架构、自定义 UI 注入等核心原理。

安装

npm install @huyooo/ai-chat-frontend-react

快速开始

import { ChatPanel } from '@huyooo/ai-chat-frontend-react'
import '@huyooo/ai-chat-frontend-react/style.css'
import { createElectronAdapter } from '@huyooo/ai-chat-bridge-electron/renderer'

const adapter = createElectronAdapter()

function App() {
  return <ChatPanel adapter={adapter} />
}

组件

ChatPanel

主聊天面板组件。

<ChatPanel
  adapter={adapter}
  workingDir="/path/to/dir"
  defaultModel="anthropic/claude-opus-4.5"
  defaultMode="agent"
  models={modelList}
  hideHeader={false}
  welcomeConfig={welcomeConfig}
  onClose={handleClose}
/>

Props

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | adapter | ChatAdapter | 必填 | 通信适配器 | | workingDir | string | - | 工作目录 | | defaultModel | string | 'anthropic/claude-opus-4.5' | 默认模型 | | defaultMode | ChatMode | 'agent' | 默认模式 | | models | ModelOption[] | [] | 可用模型列表 | | hideHeader | boolean | false | 是否隐藏标题栏 | | welcomeConfig | Partial<WelcomeConfig> | - | 欢迎页配置 | | stepsExpandedType | 'open' \| 'close' \| 'auto' | 'auto' | 执行步骤展开模式 | | toolRenderers | ToolRenderers | {} | 自定义工具结果渲染器 | | blockRenderers | BlockRenderers | {} | 自定义内容块渲染器 | | autoRunConfig | AutoRunConfig | - | 自动运行配置 | | onClose | () => void | - | 关闭回调 | | onToolComplete | (event: ToolCompleteEvent) => void | - | 工具执行完成回调 |

stepsExpandedType 说明

控制工具执行步骤的默认展开/折叠行为：

| 值 | 说明 | |---|------| | 'open' | 始终展开所有步骤 | | 'close' | 始终折叠所有步骤 | | 'auto' | 正在执行的步骤展开，执行完毕自动折叠 |

autoRunConfig 说明

自动运行配置用于控制 Agent 的工具执行行为：

interface AutoRunConfig {
  mode?: 'run-everything' | 'manual';  // 自动运行模式
}

配置项说明：

• mode: 自动运行模式
  • 'run-everything': 运行所有内容（自动执行）
  • 'manual': 手动批准模式（每次执行前询问）

使用示例：

<ChatPanel
  adapter={adapter}
  workingDir={workingDir}
  autoRunConfig={{
    mode: 'run-everything',
  }}
/>

WelcomeMessage

欢迎页组件，支持自定义配置。

<WelcomeMessage config={welcomeConfig} onQuickAction={handleQuickAction} />

欢迎页配置

可以通过 welcomeConfig 自定义欢迎页的标题、功能列表和快捷任务。

import type { WelcomeConfig } from '@huyooo/ai-chat-frontend-react'

const welcomeConfig: Partial<WelcomeConfig> = {
  // 标题区域
  title: '文件助手',
  subtitle: '智能文件管理 · 代码分析',
  icon: 'lucide:folder',
  
  // 功能列表
  features: [
    { name: '执行命令', icon: 'lucide:terminal' },
    { name: '文件分析', icon: 'lucide:file-search' },
    { name: '代码生成', icon: 'lucide:code' },
  ],
  
  // 快捷任务
  tasks: [
    {
      name: '列出文件',
      desc: '查看目录内容',
      prompt: '列出当前目录的文件',
      icon: 'lucide:list',
    },
    {
      name: '代码分析',
      desc: '分析代码结构',
      prompt: '分析这个项目的代码结构',
      icon: 'lucide:code',
    },
  ],
}

配置接口

interface WelcomeConfig {
  /** 标题 */
  title: string
  /** 副标题 */
  subtitle: string
  /** 图标 (Iconify 格式) */
  icon: string
  /** 功能列表 */
  features: WelcomeFeature[]
  /** 快捷任务 */
  tasks: WelcomeTask[]
}

interface WelcomeFeature {
  name: string
  icon: string
}

interface WelcomeTask {
  name: string
  desc: string
  prompt: string
  icon: string
}

默认配置

如果不传 welcomeConfig，将使用内置的默认配置。也可以只覆盖部分字段：

// 只修改标题，其他使用默认
const welcomeConfig = {
  title: '我的 AI 助手',
  subtitle: '智能对话工具',
}

可以导入默认配置作为基础：

import { defaultWelcomeConfig } from '@huyooo/ai-chat-frontend-react'

const welcomeConfig = {
  ...defaultWelcomeConfig,
  title: '自定义标题',
}

自定义工具结果渲染器

可以为特定工具注入自定义渲染组件，替代默认的 JSON 显示：

import { useMemo } from 'react'
import { ChatPanel, ToolRenderers } from '@huyooo/ai-chat-frontend-react'
import { CustomWeatherCard } from './components/CustomWeatherCard'

function App() {
  // 工具名称 -> 渲染组件映射
  const toolRenderers = useMemo<ToolRenderers>(() => ({
    get_weather: CustomWeatherCard,
    // search_web: CustomSearchResults,
  }), [])

  return (
    <ChatPanel
      adapter={adapter}
      toolRenderers={toolRenderers}
    />
  )
}

创建自定义渲染组件

// CustomWeatherCard.tsx
import { FC, useMemo } from 'react'
import type { ToolRendererProps, WeatherData } from '@huyooo/ai-chat-shared'
import './CustomWeatherCard.css'

export const CustomWeatherCard: FC<ToolRendererProps> = ({ toolResult }) => {
  const weather = useMemo<WeatherData>(() => {
    if (typeof toolResult === 'object' && toolResult !== null) {
      return toolResult as WeatherData
    }
    return { city: '未知', temperature: 0, condition: '未知' }
  }, [toolResult])

  return (
    <div className="weather-card">
      <div className="city">{weather.city}</div>
      <div className="temp">{weather.temperature}°C</div>
      <div className="condition">{weather.condition}</div>
      <div className="details">
        {weather.humidity && <span>湿度 {weather.humidity}%</span>}
        {weather.wind && <span>{weather.wind}</span>}
      </div>
    </div>
  )
}

ToolRendererProps 接口

interface ToolRendererProps {
  toolName: string      // 工具名称
  toolArgs: object      // 工具调用参数
  toolResult: unknown   // 工具返回结果
  status: 'running' | 'done' | 'error'  // 执行状态
}

内置数据类型

// 天气数据
interface WeatherData {
  city: string
  temperature: number
  condition: string
  humidity?: number
  wind?: string
}

// 搜索结果
interface SearchResultItem {
  title: string
  url: string
  snippet: string
}

自定义内容块渲染器

可以为特定内容类型注入自定义渲染组件：

import { useMemo } from 'react'
import { ChatPanel, BlockRenderers } from '@huyooo/ai-chat-frontend-react'
import { CustomMathBlock } from './components/CustomMathBlock'

function App() {
  const blockRenderers = useMemo<BlockRenderers>(() => ({
    math: CustomMathBlock,
  }), [])

  return (
    <ChatPanel
      adapter={adapter}
      blockRenderers={blockRenderers}
    />
  )
}

useChat

Hook 函数，用于自定义 UI。

import { useChat } from '@huyooo/ai-chat-frontend-react'

const {
  messages,
  isLoading,
  sendMessage,
  regenerateMessage,
  abort,
  clearHistory,
} = useChat({ adapter })

导出

// 主组件
export { ChatPanel, WelcomeMessage, ChatInput, ChatHeader, MessageBubble }

// 内容渲染组件
export { ContentRenderer, TextBlock, CodeBlock }

// 工具结果渲染组件
export { ToolResultRenderer, DefaultToolResult, WeatherCard, SearchResults }

// Context Provider
export { RenderersProvider, BlockRenderersContext, ToolRenderersContext }

// Hook
export { useChat }

// 类型 (来自 @huyooo/ai-chat-shared)
export type {
  WelcomeConfig,
  WelcomeFeature,
  WelcomeTask,
  ToolRendererProps,
  ToolRenderers,
  BlockRenderers,
  WeatherData,
  SearchResultItem,
  ContentBlock,
  TextBlock,
  CodeBlock
}

// 工具函数 (来自 @huyooo/ai-chat-shared)
export { parseContent, highlightCode, getLanguageDisplayName }

// 默认配置
export { defaultWelcomeConfig }

License

MIT