react-ai-renderer 0.1.4 → 0.1.6

package/README.md

@@ -1,25 +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 流程图、时序图等（可选功能）
-- **自定义组件**：支持用户注册自定义组件和生命周期钩子
-- **兼容性**：兼容现代 React 版本，提供 TypeScript 类型定义
+- **Mermaid 图表**：支持流程图、时序图等（可选功能）
 
-## 📦 安装
+## 📦 安装使用
 
 ```bash
 npm install react-ai-renderer
@@ -41,9 +66,7 @@ npm install mermaid
 
 如果不安装 mermaid，图表将不会渲染，但不会影响其他功能。
 
-## 🚀 快速开始
-
-查看 [examples/example.tsx](./examples/example.tsx) 文件了解完整的使用示例。
+## 🎯 快速开始
 
 ### 基础使用
 
@@ -51,8 +74,9 @@ npm install mermaid
 import ReactAIRenderer from 'react-ai-renderer';
 
 const content = `
-# 标题
-这是一个段落。
+# 欢迎使用 React AI Renderer
+
+这是一个 **粗体** 文本和 *斜体* 文本。
 
 \`\`\`javascript
 console.log('Hello World');
@@ -64,288 +88,242 @@ function App() {
 }
 ```
 
-### AI 推理展示
+### AI 流式输出渲染
 
 ```tsx
 import ReactAIRenderer from 'react-ai-renderer';
 
-const content = `
-<Think>
+// 模拟 AI 流式输出内容
+const aiContent = `
 正在分析用户需求...
 
-根据分析结果，我建议您使用以下方案：
-
-1. 方案A
-2. 方案B
-</Think>
+<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>;
-}
-```
-
-## 🎨 UI 组件示例
-
-React AI Renderer 支持丰富的 UI 组件渲染，包括表单、表格、卡片等常见组件。
-
-### 表单组件
-
-```mdx
-<form>
-  <Input label="姓名" placeholder="请输入姓名" />
-  <Input label="邮箱" type="email" placeholder="请输入邮箱" />
-  <Select label="性别">
-    <option value="">请选择</option>
-    <option value="male">男</option>
-    <option value="female">女</option>
-  </Select>
-  <Textarea label="个人简介" placeholder="请简单介绍一下自己" />
-  <Checkbox label="同意用户协议" />
-  <Button type="submit">提交</Button>
-  <Button type="button" style="backgroundColor: #6c757d">取消</Button>
-</form>
-```
-
-### 表格组件
-
-```mdx
-<Table>
-  <TableHeader>
-    <TableCell header>产品名称</TableCell>
-    <TableCell header>价格</TableCell>
-    <TableCell header>库存</TableCell>
-    <TableCell header>状态</TableCell>
-  </TableHeader>
-  <TableRow>
-    <TableCell>iPhone 15</TableCell>
-    <TableCell>¥5999</TableCell>
-    <TableCell>50</TableCell>
-    <TableCell>在售</TableCell>
-  </TableRow>
-  <TableRow>
-    <TableCell>MacBook Pro</TableCell>
-    <TableCell>¥12999</TableCell>
-    <TableCell>20</TableCell>
-    <TableCell>在售</TableCell>
-  </TableRow>
-  <TableRow>
-    <TableCell>iPad Air</TableCell>
-    <TableCell>¥4399</TableCell>
-    <TableCell>0</TableCell>
-    <TableCell>缺货</TableCell>
-  </TableRow>
-</Table>
-```
-
-### 卡片组件
-
-```mdx
-<Card>
-  <CardTitle>MacBook Pro</CardTitle>
-  <CardContent>
-    <p>强大的性能，适用于专业工作负载</p>
-    <p><strong>价格:</strong> ¥12999</p>
-    <p><strong>库存:</strong> 20台</p>
-  </CardContent>
-  <CardActions>
-    <Button>加入购物车</Button>
-    <Button>查看详情</Button>
-    <Button style="backgroundColor: #28a745">立即购买</Button>
-  </CardActions>
-</Card>
-```
-
-## 🛠️ API
+## 🛠️ API 参考
 
 ### ReactAIRenderer 组件
 
-主渲染组件，兼容 ReactMarkdown API。
+主渲染组件，完全兼容 ReactMarkdown API。
 
-```tsx
-interface ReactAIRendererProps {
-  children: string;
-  components?: Record<string, React.ComponentType<any>>;
-  componentHandlers?: ComponentHandler[];
-  remarkPlugins?: any[];
-  rehypePlugins?: any[];
-  scope?: any;
-  [key: string]: any;
-}
-```
+Props:
+- `content`: Markdown/MDX 内容字符串
+- `scope`: 传递给 MDX 的作用域对象
+- `components`: 自定义组件映射
+- `componentHandlers`: 组件处理器数组（支持生命周期钩子）
+- `children`: 作为内容的子元素（替代 content）
 
-### ComponentHandler 接口
+### 组件生命周期钩子
 
-用于注册自定义组件和生命周期钩子。
+通过 `componentHandlers` 属性可以为组件添加生命周期钩子：
 
 ```tsx
-interface ComponentHandler {
-  component: React.ComponentType<any>;
-  name: string;
-  selfClosing: boolean;
-  onRender?: (item: ComponentData, scope: any) => void;
-}
+const componentHandlers = [
+  {
+    name: 'MyComponent',
+    component: MyComponent,
+    selfClosing: false,
+    onRender: (item, scope) => {
+      // 组件渲染完成后的回调
+      console.log('组件已渲染:', item);
+    }
+  }
+];
 ```
 
-## 🧩 内置组件
+## ⚡ 性能优势
 
-### Think 组件
+### 实时渲染
+- 流式解析，无需等待完整内容
+- 动态组件渲染，提升用户体验
+- 内存优化，避免重复渲染
 
-用于展示 AI 推理过程的组件。使用 `<Think>` 标签包围需要展示为推理过程的内容。
+### 兼容性保障
+- 完全兼容 React 18+
+- 支持 TypeScript 类型安全
+- 无依赖冲突，轻松集成
 
-```tsx
-<Think>
-正在分析用户需求...
-</Think>
-```
+## 💡 应用场景
 
-Think 组件会自动识别 `<Think>` 标签并将其内容渲染为可折叠的推理过程展示。
+### 1. AI 助手应用
+让 AI 助手直接输出交互式 UI，提升用户体验
 
-### CodeHighlight 组件
+### 2. 代码生成工具
+AI 生成的代码可以直接渲染为可交互的组件
 
-支持多种编程语言的代码高亮显示。
+### 3. 数据分析报告
+AI 分析结果可直接渲染为图表和表格
 
-### MermaidRenderer 组件
+### 4. 教育培训系统
+AI 生成的教学内容可直接渲染为交互式课件
 
-动态加载和渲染 Mermaid 图表。
+### 5. 智能文档系统
+AI 生成的文档可直接渲染为富交互页面
 
-> 注意：Mermaid 是一个 peer dependency，需要在项目中单独安装。如果未安装 mermaid，图表将显示为代码块并提示安装信息。
+### 6. 低代码平台
+AI 辅助生成界面，直接渲染为可用组件
 
-## 🏗️ 构建配置
+### 7. 自动化运维
+AI 分析结果可直接渲染为操作界面
 
-使用 Rollup 进行构建，输出 UMD 和 ESM 两种格式。
+## 📖 示例运行
 
-### 构建命令
+运行示例：
 
 ```bash
-npm run build
+npm run example
 ```
 
-### 开发模式
+然后在浏览器中访问 http://localhost:3000
+
+## 🧪 测试
 
 ```bash
-npm run dev
+npm test
 ```
 
-### 运行示例
+## 🚀 高级特性
 
-#### 浏览器示例（推荐）
+### 流式渲染优化
+React AI Renderer 采用先进的流式解析技术，能够在 AI 模型输出的同时实时渲染内容，无需等待完整输出。
 
-构建项目和示例：
+### 组件注册机制
+支持动态组件注册，可以灵活扩展自定义组件：
 
-```bash
-npm run build
-npm run build:examples
-```
-
-然后使用以下命令启动示例：
+```tsx
+const customComponents = {
+  MyButton: ({ onClick, children }) => (
+    <button onClick={onClick} className="custom-button">
+      {children}
+    </button>
+  )
+};
 
-```bash
-npm run example
+<ReactAIRenderer components={customComponents}>
+  {content}
+</ReactAIRenderer>
 ```
 
-这将启动一个本地服务器，并在浏览器中打开示例页面。
+### 作用域传递
+支持向组件传递作用域变量，实现更复杂的数据交互：
 
-您也可以直接在浏览器中打开 [examples/example.html](./examples/example.html) 文件查看示例效果。
+```tsx
+const scope = {
+  userData: { name: "张三", age: 25 },
+  onAction: (data) => console.log("Action triggered:", data)
+};
 
-示例页面现在使用本地构建的 React 依赖，不再依赖外部 CDN 链接，确保在任何环境下都能正常运行。
+<ReactAIRenderer scope={scope}>
+  {content}
+</ReactAIRenderer>
+```
 
-#### Node.js 示例
+## 📊 架构设计
 
-如果您想快速查看 API 使用方式，可以运行 Node.js 示例：
+### 系统架构图
 
-```bash
-npm run example:node
+```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]
 ```
 
-这将展示如何在 Node.js 环境中使用该库，并演示服务端渲染的基本用法。注意：由于 ReactAIRenderer 是一个 React 组件，它需要浏览器环境才能完全渲染，在 Node.js 环境中只能查看 API 使用方式和基本的服务端渲染输出。
+### 工作流程
 
-## 📁 项目结构
+1. AI 模型流式输出 JSX/XML 格式的内容
+2. React AI Renderer 实时接收并解析内容
+3. MDX Streaming Parser 动态解析组件数据
+4. Component Renderer 渲染自定义 UI 组件
+5. 触发生命周期钩子，执行后续动作
 
-```
-react-ai-renderer/
-├── src/
-│   ├── index.ts                # 入口文件
-│   ├── ReactAIRenderer.tsx     # 主渲染组件
-│   ├── types.ts                # 类型定义
-│   ├── components/             # 内置组件
-│   │   ├── BuiltInComponents.tsx # 内置组件集合
-│   │   ├── CodeHighlight.tsx     # 代码高亮组件
-│   │   ├── ErrorBoundary.tsx     # 错误边界组件
-│   │   ├── ErrorUI.tsx           # 错误展示组件
-│   │   ├── MdxLayout.tsx         # MDX 布局组件
-│   │   ├── MermaidRenderer.tsx   # Mermaid 图表渲染组件
-│   │   ├── Think.tsx             # AI 推理展示组件
-│   │   └── ToolCall.tsx          # 工具调用展示组件
-│   └── utils/                  # 工具函数
-│       ├── contentProcessor.ts   # 内容处理工具
-│       ├── mdxRenderer.ts        # MDX 渲染工具
-│       └── mdxStreamParse.ts     # MDX 流式解析工具
-├── dist/                       # 构建输出目录
-├── examples/                   # 示例文件
-│   ├── components/             # UI 组件示例
-│   │   ├── FormComponents.tsx    # 表单组件
-│   │   ├── TableComponents.tsx   # 表格组件
-│   │   ├── CardComponents.tsx    # 卡片组件
-│   │   └── index.ts              # 组件导出
-│   ├── example.tsx             # React 示例
-│   ├── example.html            # HTML 示例
-│   ├── run-example.js          # Node.js 示例
-│   ├── tsconfig.json           # 示例编译配置
-│   └── dist/                   # 编译后的示例文件
-├── package.json                # 包配置文件
-├── tsconfig.json               # TypeScript 配置
-├── rollup.config.js            # Rollup 构建配置
-└── README.md                   # 项目说明文档
-```
+## ❓ 常见问题
 
-## 🤝 贡献
+### Q: React AI Renderer 与 react-markdown 有什么区别？
+A: React AI Renderer 完全兼容 react-markdown，但增加了对 JSX/XML 组件的支持、流式渲染和生命周期钩子等高级功能。
 
-欢迎提交 Issue 和 Pull Request 来改进这个项目。
+### Q: 如何处理未注册的组件？
+A: 未注册的组件会自动转换为对应的文本表示形式，不会导致页面崩溃。
 
-## 📄 许可证
+### Q: 是否支持不同组件库如antd,shadcn等
+A: 是的，React AI Renderer 无组件依赖，你可以使用任意组件库以及自定义组件
 
-MIT
+### Q: 性能如何优化？
+A: 建议合理使用组件生命周期钩子，避免在渲染过程中执行耗时操作。
 
-## 🙏 致谢
+## 📄 许可证
 
-- [MDX](https://mdxjs.com/) - Markdown for the component era
-- [Remark](https://remark.js.org/) - Markdown processor powered by plugins
-- [Rehype](https://github.com/rehypejs/rehype) - HTML processor powered by plugins
-- [Mermaid](https://mermaid-js.github.io/) - Generation of diagram and flowchart from text in a similar manner as markdown
+MIT