@huyooo/ai-chat-frontend-react 0.1.6 → 0.1.8

package/README.md

@@ -0,0 +1,368 @@
+# @huyooo/ai-chat-frontend-react
+
+AI Chat 前端组件库 - React 版本。
+
+> 📖 **深入了解**：查看 [技术架构文档](../../ARCHITECTURE.md) 了解流式渲染、Content Parts 架构、自定义 UI 注入等核心原理。
+
+## 安装
+
+```bash
+npm install @huyooo/ai-chat-frontend-react
+```
+
+## 快速开始
+
+```tsx
+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
+
+主聊天面板组件。
+
+```tsx
+<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 的工具执行行为：
+
+```typescript
+interface AutoRunConfig {
+  mode?: 'run-everything' | 'manual';  // 自动运行模式
+}
+```
+
+**配置项说明：**
+
+- **mode**: 自动运行模式
+  - `'run-everything'`: 运行所有内容（自动执行）
+  - `'manual'`: 手动批准模式（每次执行前询问）
+
+**使用示例：**
+
+```tsx
+<ChatPanel
+  adapter={adapter}
+  workingDir={workingDir}
+  autoRunConfig={{
+    mode: 'run-everything',
+  }}
+/>
+```
+
+### WelcomeMessage
+
+欢迎页组件，支持自定义配置。
+
+```tsx
+<WelcomeMessage config={welcomeConfig} onQuickAction={handleQuickAction} />
+```
+
+## 欢迎页配置
+
+可以通过 `welcomeConfig` 自定义欢迎页的标题、功能列表和快捷任务。
+
+```typescript
+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',
+    },
+  ],
+}
+```
+
+### 配置接口
+
+```typescript
+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`，将使用内置的默认配置。也可以只覆盖部分字段：
+
+```typescript
+// 只修改标题，其他使用默认
+const welcomeConfig = {
+  title: '我的 AI 助手',
+  subtitle: '智能对话工具',
+}
+```
+
+可以导入默认配置作为基础：
+
+```typescript
+import { defaultWelcomeConfig } from '@huyooo/ai-chat-frontend-react'
+
+const welcomeConfig = {
+  ...defaultWelcomeConfig,
+  title: '自定义标题',
+}
+```
+
+## 自定义工具结果渲染器
+
+可以为特定工具注入自定义渲染组件，替代默认的 JSON 显示：
+
+```tsx
+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}
+    />
+  )
+}
+```
+
+### 创建自定义渲染组件
+
+```tsx
+// 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 接口
+
+```typescript
+interface ToolRendererProps {
+  toolName: string      // 工具名称
+  toolArgs: object      // 工具调用参数
+  toolResult: unknown   // 工具返回结果
+  status: 'running' | 'done' | 'error'  // 执行状态
+}
+```
+
+### 内置数据类型
+
+```typescript
+// 天气数据
+interface WeatherData {
+  city: string
+  temperature: number
+  condition: string
+  humidity?: number
+  wind?: string
+}
+
+// 搜索结果
+interface SearchResultItem {
+  title: string
+  url: string
+  snippet: string
+}
+```
+
+## 自定义内容块渲染器
+
+可以为特定内容类型注入自定义渲染组件：
+
+```tsx
+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。
+
+```typescript
+import { useChat } from '@huyooo/ai-chat-frontend-react'
+
+const {
+  messages,
+  isLoading,
+  sendMessage,
+  regenerateMessage,
+  abort,
+  clearHistory,
+} = useChat({ adapter })
+```
+
+## 导出
+
+```typescript
+// 主组件
+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