react-ai-renderer 0.1.5 → 0.1.6

package/README.md

@@ -1,26 +1,50 @@
-# React AI Renderer
+# React AI Renderer - AI 应用的专属渲染器
 
 [English](./README_en.md) | 中文
 
-一个专为 AI 应用程序设计的 React 渲染器，支持流式 Markdown 和 MDX 内容渲染，提供代码高亮、数学公式、Mermaid 图表等增强功能。
+> 一个专为 AI 应用程序设计的 UI 渲染器，可以极大增强 AI 与前端的交互方式。支持流式 JSX/XML 渲染、自定义组件、生命周期钩子，让 AI 输出直接变为交互式 UI。
 
-## 📋 环境要求
 
-- Node.js 20.x 或更高版本
-- React 18.x 或更高版本
+<p align="center">
+  <img src="./examples/demo-assets/react-ai-renderer.gif" alt="React AI Renderer Demo" width="800" />
+</p>
+<p align="center"><em>React AI Renderer - 实现 AI 输出到交互式 UI 的无缝转换</em></p>
 
-## 🌟 特性
+## 🚀 项目愿景
 
-- **流式渲染**：支持逐步渲染 AI 流式输出的 Markdown/MDX 内容
+在 AI 应用井喷式爆发的今天，以 Chat Bot 为核心的交互已成为主流。然而，传统的文本化输出方式远远无法满足现代 AI 应用对视觉渲染效果的需求。React AI Renderer 提供了完美的解决方案：
+
+### 传统方式的痛点
+
+1. **等待问题**：LLM 是流式输出的，但 JSON 必须等流结束才能完整交付给前端渲染
+2. **构建成本高**：构建 JSON 和约定渲染本身成本较高，也容易出错
+3. **缺乏生命周期管理**：无法在渲染之后触发动作，传统 Markdown 渲染器无法满足复杂交互需求
+
+### React AI Renderer 的解决方案
+
+React AI Renderer 彻底解决了上述问题，让 AI 可以直接输出标准的 JSX/XML 语法糖，由前端实时渲染为交互式 UI，同时支持完整的生命周期管理。
+
+## 🌟 核心特性
+
+### ✅ 无缝兼容 React Markdown
+只需将引入名称从 `react-markdown` 改为 `react-ai-renderer`，即可无感知继承现有能力，零成本迁移。
+
+### ✅ 自定义组件渲染
+支持基于项目已有的前端 UI 进行渲染，无限拉高产品体验上限，复用现有视觉主题。
+
+### ✅ 真正的流式渲染
+动态 token 对应动态解析，无需像 JSON 格式那样等待模型输出完毕才能看到视觉效果。
+
+### ✅ 组件生命周期钩子
+单一组件渲染完毕后可触发下一个事件，轻松实现文件列表+文件内容左右分栏等复杂交互效果。
+
+### ✅ 丰富的内置组件
 - **AI 推理展示**：内置 Think 组件展示 AI 思考过程
 - **代码高亮**：支持多种编程语言的代码高亮显示
 - **数学公式**：使用 KaTeX 渲染数学公式
-- **Mermaid 图表**：支持 Mermaid 流程图、时序图等（可选功能）
-- **GitHub样式**：使用GitHub风格的Markdown渲染样式
-- **自定义组件**：支持用户注册自定义组件和生命周期钩子
-- **兼容性**：兼容现代 React 版本，提供 TypeScript 类型定义
+- **Mermaid 图表**：支持流程图、时序图等（可选功能）
 
-## 📦 安装
+## 📦 安装使用
 
 ```bash
 npm install react-ai-renderer
@@ -42,51 +66,7 @@ npm install mermaid
 
 如果不安装 mermaid，图表将不会渲染，但不会影响其他功能。
 
-## 🎨 GitHub风格样式
-
-React AI Renderer 现在支持 GitHub 风格的 Markdown 渲染样式，使渲染的 Markdown 内容具有与 GitHub 上相同的外观和感觉。
-
-### 特性
-
-- GitHub风格的排版和间距
-- 代码块的语法高亮
-- 表格样式优化
-- 链接样式
-- 标题样式（包括下划线效果）
-- 引用块样式
-- 列表样式优化
-
-### 使用方法
-
-组件会自动应用GitHub样式，无需额外配置：
-
-```jsx
-import ReactAIRenderer from 'react-ai-renderer';
-
-function MyComponent() {
-  const markdownContent = `
-# 标题
-
-这是一个 **粗体** 文本和 *斜体* 文本。
-
-\`\`\`javascript
-console.log('Hello, World!');
-\`\`\`
-
-| 列1 | 列2 |
-|-----|-----|
-| 数据1 | 数据2 |
-`;
-
-  return <ReactAIRenderer content={markdownContent} />;
-}
-```
-
-查看 [GITHUB_STYLE_USAGE.md](./GITHUB_STYLE_USAGE.md) 获取更多使用详情。
-
-## 🚀 快速开始
-
-查看 [examples/example.tsx](./examples/example.tsx) 文件了解完整的使用示例。
+## 🎯 快速开始
 
 ### 基础使用
 
@@ -94,8 +74,9 @@ console.log('Hello, World!');
 import ReactAIRenderer from 'react-ai-renderer';
 
 const content = `
-# 标题
-这是一个段落。
+# 欢迎使用 React AI Renderer
+
+这是一个 **粗体** 文本和 *斜体* 文本。
 
 \`\`\`javascript
 console.log('Hello World');
@@ -107,92 +88,154 @@ function App() {
 }
 ```
 
-### AI 推理展示
+### AI 流式输出渲染
 
 ```tsx
 import ReactAIRenderer from 'react-ai-renderer';
 
-const content = `
+// 模拟 AI 流式输出内容
+const aiContent = `
 正在分析用户需求...
 
-根据分析结果，我建议您使用以下方案：
-
-1. 方案A
-2. 方案B
+<Table>
+  <TableHeader>
+    <TableCell header>产品名称</TableCell>
+    <TableCell header>价格</TableCell>
+    <TableCell header>库存</TableCell>
+  </TableHeader>
+  <TableRow>
+    <TableCell>iPhone 15</TableCell>
+    <TableCell>¥5999</TableCell>
+    <TableCell>50</TableCell>
+  </TableRow>
+</Table>
 `;
 
 function App() {
-  return <ReactAIRenderer>{content}</ReactAIRenderer>;
+  return <ReactAIRenderer>{aiContent}</ReactAIRenderer>;
 }
 ```
 
-### 自定义组件
+### 自定义组件与生命周期
 
 ```tsx
 import ReactAIRenderer from 'react-ai-renderer';
 
-const customComponents = {
-  Button: (props) => <button {...props} style={{ backgroundColor: 'blue', color: 'white' }} />
-};
+// 自定义按钮组件
+const Button = ({ onClick, children, style }) => (
+  <button 
+    onClick={onClick} 
+    style={{ 
+      backgroundColor: 'blue', 
+      color: 'white',
+      padding: '8px 16px',
+      border: 'none',
+      borderRadius: '4px',
+      cursor: 'pointer',
+      ...style
+    }}
+  >
+    {children}
+  </button>
+);
+
+// 组件生命周期钩子
+const componentHandlers = [
+  {
+    name: 'Button',
+    component: Button,
+    selfClosing: false,
+    onRender: (item, scope) => {
+      console.log('Button 组件已渲染完成');
+      // 可以在这里触发下一个动作
+      // 例如：更新状态、发送请求等
+    }
+  }
+];
 
 const content = `
 <Button onClick={() => alert('点击了按钮')}>点击我</Button>
 `;
 
 function App() {
-  return <ReactAIRenderer components={customComponents}>{content}</ReactAIRenderer>;
+  return (
+    <ReactAIRenderer 
+      components={{ Button }} 
+      componentHandlers={componentHandlers}
+    >
+      {content}
+    </ReactAIRenderer>
+  );
 }
 ```
 
-### 图表渲染
-
-```tsx
-import ReactAIRenderer from 'react-ai-renderer';
-
-const content = `
-\`\`\`mermaid
-graph TD
-  A[开始] --> B[处理]
-  B --> C[结束]
-\`\`\`
-`;
-
-function App() {
-  return <ReactAIRenderer>{content}</ReactAIRenderer>;
-}
-```
-
-## 🛠️ API
+## 🛠️ API 参考
 
 ### ReactAIRenderer 组件
 
-主渲染组件，兼容 ReactMarkdown API。
+主渲染组件，完全兼容 ReactMarkdown API。
 
 Props:
 - `content`: Markdown/MDX 内容字符串
 - `scope`: 传递给 MDX 的作用域对象
 - `components`: 自定义组件映射
-- `componentHandlers`: 组件处理器数组
+- `componentHandlers`: 组件处理器数组（支持生命周期钩子）
 - `children`: 作为内容的子元素（替代 content）
 
-### Think 组件
+### 组件生命周期钩子
 
-用于展示 AI 思考过程的组件。
+通过 `componentHandlers` 属性可以为组件添加生命周期钩子：
 
-Props:
-- `title`: 思考步骤标题
-- `children`: 思考内容
+```tsx
+const componentHandlers = [
+  {
+    name: 'MyComponent',
+    component: MyComponent,
+    selfClosing: false,
+    onRender: (item, scope) => {
+      // 组件渲染完成后的回调
+      console.log('组件已渲染:', item);
+    }
+  }
+];
+```
 
-### ToolCall 组件
+## ⚡ 性能优势
 
-用于展示工具调用过程的组件。
+### 实时渲染
+- 流式解析，无需等待完整内容
+- 动态组件渲染，提升用户体验
+- 内存优化，避免重复渲染
 
-Props:
-- `name`: 工具名称
-- `parameters`: 工具参数
-- `result`: 工具调用结果
+### 兼容性保障
+- 完全兼容 React 18+
+- 支持 TypeScript 类型安全
+- 无依赖冲突，轻松集成
+
+## 💡 应用场景
+
+### 1. AI 助手应用
+让 AI 助手直接输出交互式 UI，提升用户体验
 
-## 📖 示例
+### 2. 代码生成工具
+AI 生成的代码可以直接渲染为可交互的组件
+
+### 3. 数据分析报告
+AI 分析结果可直接渲染为图表和表格
+
+### 4. 教育培训系统
+AI 生成的教学内容可直接渲染为交互式课件
+
+### 5. 智能文档系统
+AI 生成的文档可直接渲染为富交互页面
+
+### 6. 低代码平台
+AI 辅助生成界面，直接渲染为可用组件
+
+### 7. 自动化运维
+AI 分析结果可直接渲染为操作界面
+
+## 📖 示例运行
 
 运行示例：
 
@@ -200,7 +243,7 @@ Props:
 npm run example
 ```
 
-然后在浏览器中访问 http://localhost:3000/examples/example.html
+然后在浏览器中访问 http://localhost:3000
 
 ## 🧪 测试
 
@@ -208,6 +251,79 @@ npm run example
 npm test
 ```
 
+## 🚀 高级特性
+
+### 流式渲染优化
+React AI Renderer 采用先进的流式解析技术，能够在 AI 模型输出的同时实时渲染内容，无需等待完整输出。
+
+### 组件注册机制
+支持动态组件注册，可以灵活扩展自定义组件：
+
+```tsx
+const customComponents = {
+  MyButton: ({ onClick, children }) => (
+    <button onClick={onClick} className="custom-button">
+      {children}
+    </button>
+  )
+};
+
+<ReactAIRenderer components={customComponents}>
+  {content}
+</ReactAIRenderer>
+```
+
+### 作用域传递
+支持向组件传递作用域变量，实现更复杂的数据交互：
+
+```tsx
+const scope = {
+  userData: { name: "张三", age: 25 },
+  onAction: (data) => console.log("Action triggered:", data)
+};
+
+<ReactAIRenderer scope={scope}>
+  {content}
+</ReactAIRenderer>
+```
+
+## 📊 架构设计
+
+### 系统架构图
+
+```mermaid
+graph TD
+    A[AI Model] -->|Streaming Output| B[React AI Renderer]
+    B -->|Parse JSX/XML| C[MDX Streaming Parser]
+    C -->|Component Data| D[Component Renderer]
+    D -->|Render Components| E[Custom UI Components]
+    D -->|Lifecycle Hooks| F[Event Triggers]
+    E --> G[Interactive UI]
+    F --> H[Next Actions]
+```
+
+### 工作流程
+
+1. AI 模型流式输出 JSX/XML 格式的内容
+2. React AI Renderer 实时接收并解析内容
+3. MDX Streaming Parser 动态解析组件数据
+4. Component Renderer 渲染自定义 UI 组件
+5. 触发生命周期钩子，执行后续动作
+
+## ❓ 常见问题
+
+### Q: React AI Renderer 与 react-markdown 有什么区别？
+A: React AI Renderer 完全兼容 react-markdown，但增加了对 JSX/XML 组件的支持、流式渲染和生命周期钩子等高级功能。
+
+### Q: 如何处理未注册的组件？
+A: 未注册的组件会自动转换为对应的文本表示形式，不会导致页面崩溃。
+
+### Q: 是否支持不同组件库如antd,shadcn等
+A: 是的，React AI Renderer 无组件依赖，你可以使用任意组件库以及自定义组件
+
+### Q: 性能如何优化？
+A: 建议合理使用组件生命周期钩子，避免在渲染过程中执行耗时操作。
+
 ## 📄 许可证
 
 MIT