@huyooo/ai-chat-frontend-react 0.2.13 → 0.2.14

package/README.md

@@ -39,6 +39,7 @@ function App() {
   models={modelList}
   hideHeader={false}
   welcomeConfig={welcomeConfig}
+  partRenderers={partRenderers}
   onClose={handleClose}
 />
 ```
@@ -55,8 +56,7 @@ function App() {
 | `hideHeader` | `boolean` | `false` | 是否隐藏标题栏 |
 | `welcomeConfig` | `Partial<WelcomeConfig>` | - | 欢迎页配置 |
 | `stepsExpandedType` | `'open' \| 'close' \| 'auto'` | `'auto'` | 执行步骤展开模式 |
-| `toolRenderers` | `ToolRenderers` | `{}` | 自定义工具结果渲染器 |
-| `blockRenderers` | `BlockRenderers` | `{}` | 自定义内容块渲染器 |
+| `partRenderers` | `PartRenderers` | `{}` | 自定义 Part 类型渲染器 |
 | `autoRunConfig` | `AutoRunConfig` | - | 自动运行配置 |
 | `onClose` | `() => void` | - | 关闭回调 |
 | `onToolComplete` | `(event: ToolCompleteEvent) => void` | - | 工具执行完成回调 |
@@ -197,26 +197,45 @@ const welcomeConfig = {
 }
 ```
 
-## 自定义工具结果渲染器
+## 自定义 Part 渲染器（新架构）
 
-可以为特定工具注入自定义渲染组件，替代默认的 JSON 显示：
+新架构使用 `partRenderers` 为特定的 Part 类型注入自定义渲染组件。工具执行结果会直接生成对应类型的 Part（如 `weather`），前端根据 `part.type` 选择渲染组件。
+
+### 工作原理
+
+```
+工具执行完成
+    ↓
+后端发送 tool_call_result { id, name, result, resultType: 'weather' }
+    ↓
+前端 useChat 处理：
+  1. 更新 tool_call 状态为 done
+  2. 根据 resultType 创建 { type: 'weather', ...result } Part
+    ↓
+PartsRenderer 渲染：
+  - 检查 partRenderers['weather']
+  - 找到 → 使用自定义 WeatherCard 渲染
+  - 没找到 → 显示 JSON fallback
+```
+
+### 使用示例
 
 ```tsx
 import { useMemo } from 'react'
-import { ChatPanel, ToolRenderers } from '@huyooo/ai-chat-frontend-react'
+import { ChatPanel, PartRenderers } from '@huyooo/ai-chat-frontend-react'
 import { CustomWeatherCard } from './components/CustomWeatherCard'
 
 function App() {
-  // 工具名称 -> 渲染组件映射
-  const toolRenderers = useMemo<ToolRenderers>(() => ({
-    get_weather: CustomWeatherCard,
-    // search_web: CustomSearchResults,
+  // Part 类型 -> 渲染组件映射
+  const partRenderers = useMemo<PartRenderers>(() => ({
+    weather: CustomWeatherCard,  // weather 类型使用自定义卡片
+    // stock: CustomStockCard,
   }), [])
 
   return (
     <ChatPanel
       adapter={adapter}
-      toolRenderers={toolRenderers}
+      partRenderers={partRenderers}
     />
   )
 }
@@ -224,85 +243,73 @@ function App() {
 
 ### 创建自定义渲染组件
 
+自定义组件直接接收 Part 的所有字段作为 props：
+
 ```tsx
 // CustomWeatherCard.tsx
-import { FC, useMemo } from 'react'
-import type { ToolRendererProps, WeatherData } from '@huyooo/ai-chat-shared'
+import { FC } from 'react'
 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 {
+interface WeatherPartProps {
+  type: 'weather'    // Part 类型
   city: string
   temperature: number
   condition: string
   humidity?: number
   wind?: string
+  reportTime?: string
+  province?: string
 }
 
-// 搜索结果
-interface SearchResultItem {
-  title: string
-  url: string
-  snippet: string
+export const CustomWeatherCard: FC<WeatherPartProps> = ({
+  city,
+  temperature,
+  condition,
+  humidity,
+  wind,
+}) => {
+  return (
+    <div className="weather-card">
+      <div className="city">{city}</div>
+      <div className="temp">{temperature}°C</div>
+      <div className="condition">{condition}</div>
+      <div className="details">
+        {humidity && <span>湿度 {humidity}%</span>}
+        {wind && <span>{wind}</span>}
+      </div>
+    </div>
+  )
 }
 ```
 
-## 自定义内容块渲染器
+### 内置 Part 类型
 
-可以为特定内容类型注入自定义渲染组件：
+| Part 类型 | 说明 | 内置渲染器 |
+|-----------|------|-----------|
+| `text` | 文本内容 | TextPart（支持 Markdown） |
+| `thinking` | 思考过程 | ThinkingPart（可折叠卡片） |
+| `search` | 搜索结果 | SearchPart |
+| `tool_call` | 工具执行状态 | ToolCallPart（仅显示状态） |
+| `image` | 图片 | ImagePart |
+| `error` | 错误信息 | ErrorPart |
 
-```tsx
-import { useMemo } from 'react'
-import { ChatPanel, BlockRenderers } from '@huyooo/ai-chat-frontend-react'
-import { CustomMathBlock } from './components/CustomMathBlock'
+### 扩展 Part 类型
 
-function App() {
-  const blockRenderers = useMemo<BlockRenderers>(() => ({
-    math: CustomMathBlock,
-  }), [])
+可以通过工具的 `resultType` 定义新的 Part 类型：
 
-  return (
-    <ChatPanel
-      adapter={adapter}
-      blockRenderers={blockRenderers}
-    />
-  )
+```typescript
+// 后端工具定义
+export function getWeatherTool(): ToolPlugin {
+  return tool({
+    name: 'get_weather',
+    description: '获取城市天气',
+    parameters: { city: { type: 'string' } },
+    resultType: 'weather',  // ← 指定结果 Part 类型
+    execute: async (args, context) => {
+      // 返回值会自动转换为 { type: 'weather', ...result }
+      return { city: args.city, temperature: 25, condition: '晴' }
+    }
+  })
 }
 ```
 
@@ -329,31 +336,39 @@ const {
 // 主组件
 export { ChatPanel, WelcomeMessage, ChatInput, ChatHeader, MessageBubble }
 
-// 内容渲染组件
-export { ContentRenderer, TextBlock, CodeBlock }
-
-// 工具结果渲染组件
-export { ToolResultRenderer, DefaultToolResult, WeatherCard, SearchResults }
+// Part 渲染组件
+export { PartsRenderer }
+export {
+  TextPartComponent,
+  ThinkingPartComponent,
+  SearchPartComponent,
+  ToolCallPartComponent,
+  ImagePartComponent,
+  ErrorPartComponent,
+}
 
 // Context Provider
-export { RenderersProvider, BlockRenderersContext, ToolRenderersContext }
+export { PartRenderersProvider, PartRenderersContext }
 
 // Hook
 export { useChat }
 
-// 类型 (来自 @huyooo/ai-chat-shared)
+// 类型
 export type {
   WelcomeConfig,
   WelcomeFeature,
   WelcomeTask,
-  ToolRendererProps,
-  ToolRenderers,
-  BlockRenderers,
+  PartRenderers,
+  PartRendererProps,
+  ContentPart,
+  TextPart,
+  ThinkingPart,
+  SearchPart,
+  ToolCallPart,
+  ImagePart,
+  ErrorPart,
   WeatherData,
   SearchResultItem,
-  ContentBlock,
-  TextBlock,
-  CodeBlock
 }
 
 // 工具函数 (来自 @huyooo/ai-chat-shared)