@leeoohoo/aichat 1.0.10 → 1.0.11

package/README.md

@@ -1,179 +1,214 @@
 # @leeoohoo/aichat
 
-React AI Chat Component and Node server. Bilingual README (中文/English).
+一个功能完整的React AI聊天组件，支持会话管理、MCP集成和SQLite持久化存储。
 
-—
+## 特性
 
-一个功能完整的 React AI 聊天组件库，配套 Node 后端服务，支持会话管理、MCP 工具集成与持久化存储。
+- 🚀 **开箱即用** - 一个标签即可使用完整的AI聊天功能
+- 💬 **会话管理** - 支持多会话切换、创建、删除和重命名
+- 🤖 **AI模型支持** - 支持OpenAI GPT系列模型
+- 🔧 **MCP集成** - 支持Model Context Protocol工具调用
+- 💾 **数据持久化** - 基于SQLite的本地数据存储
+- 🎨 **主题切换** - 支持明暗主题切换
+- 📱 **响应式设计** - 适配各种屏幕尺寸
+- 🔒 **类型安全** - 完整的TypeScript类型定义
 
-## 功能 Features
+## 🚀 快速开始
 
-- 开箱即用 Standalone chat UI, drop-in usage
-- 会话管理 Sessions CRUD, multi-session switching
-- AI 模型配置 AI model configs (OpenAI-compatible)
-- MCP 集成 Model Context Protocol tool calls (HTTP/STDIO)
-- 数据持久化 SQLite by default (MongoDB optional in server)
-- 主题切换 Light/Dark/Auto, responsive UI
-- 类型安全 Full TypeScript types
-
-## 代码结构 Repository Structure
-
-- 根目录 Root: React 组件库 React component library (Vite + TS)
-- server/chat_app_node_server: Node API 服务 Node API server (Express, SSE, MCP, SQLite/MongoDB)
-- examples/complete-example: 集成示例 Example app (web/Electron)
-
-## 快速开始 Quick Start
-
-1) 作为依赖使用 Use as a dependency
+### 安装
 
 ```bash
+# 使用 npm 
 npm install @leeoohoo/aichat
-# or
-yarn add @leeoohoo/aichat
-# or
-pnpm add @leeoohoo/aichat
-```
-
-最简用法 Minimal usage
 
-```tsx
-import StandaloneChatInterface from '@leeoohoo/aichat';
-import '@leeoohoo/aichat/styles';
+# 或使用 yarn 
+yarn add @leeoohoo/aichat
 
-export default function App() {
-  return <StandaloneChatInterface className="h-screen" />;
-}
+# 或使用 pnpm 
+pnpm add @leeoohoo/aichat
 ```
 
-2) 本仓库本地开发 Run locally (this repo)
+### 启动后端服务
 
-- 启动后端 Start the API server
+组件需要后端API服务支持，请先启动后端服务：
 
 ```bash
-cd server/chat_app_node_server
-npm install
-cp .env.example .env   # 设置 OPENAI_API_KEY 等 set your OPENAI_API_KEY
-npm start              # http://localhost:3001
+# 方式一：使用npm脚本启动
+npx @leeoohoo/aichat start:server
+
+# 方式二：直接运行服务器文件
+node node_modules/@leeoohoo/aichat/server/index.js
 ```
 
-- 启动前端 Start the frontend demo
+后端服务默认运行在 `http://localhost:3001`，提供以下API：
+- 会话管理 (`/api/sessions`)
+- 消息管理 (`/api/messages`) 
+- MCP配置 (`/api/mcp-configs`)
+- AI模型配置 (`/api/ai-model-configs`)
+- 系统上下文 (`/api/system-context`)
 
-```bash
-cd /path/to/chat_app
-npm install
-npm run dev            # http://localhost:5173 (proxy /api → 3001)
-```
+### 基础使用（推荐）
 
-生产环境可通过组件传入 `apiBaseUrl` 或 `port` 覆盖后端地址。
-In production, pass `apiBaseUrl` or `port` to the component to point at your server.
+使用独立聊天组件，无需任何配置，开箱即用：
 
 ```tsx
-<StandaloneChatInterface apiBaseUrl="https://your.domain/api" />
-// or
-<StandaloneChatInterface port={3001} />
+import React from 'react';
+import StandaloneChatInterface from '@leeoohoo/aichat';
+import '@leeoohoo/aichat/styles';
+
+function App() {
+  return (
+    <div className="h-screen w-full">
+      <StandaloneChatInterface className="h-full" />
+    </div>
+  );
+}
+
+export default App;
 ```
 
-## 使用 Usage
+## 高级配置
 
-推荐 Recommended: 独立组件 Standalone component
+### 自定义事件处理
 
 ```tsx
-import StandaloneChatInterface from '@leeoohoo/aichat';
-import '@leeoohoo/aichat/styles';
-
-<StandaloneChatInterface
-  className="h-full"
-  userId="user_123"
-  projectId="proj_456"
-  showMcpManager
-  showAiModelManager
-  showSystemContextEditor
-  showAgentManager
-/>
+import React from 'react';
+import { ChatInterface, type Message, type Attachment } from '@leeoohoo/aichat';
+
+function App() {
+  const handleMessageSend = (content: string, attachments?: Attachment[]) => {
+    console.log('发送消息:', content, attachments);
+  };
+
+  const handleSessionChange = (sessionId: string) => {
+    console.log('切换会话:', sessionId);
+  };
+
+  return (
+    <ChatInterface
+      onMessageSend={handleMessageSend}
+      onSessionChange={handleSessionChange}
+    />
+  );
+}
 ```
 
-可选：类方式 API Optional: class-style API
+### 自定义渲染器
 
 ```tsx
-import { AiChat } from '@leeoohoo/aichat';
-
-const aiChat = new AiChat(
-  'user_123',
-  'proj_456',
-  '/api',           // configUrl (API base)
-  'h-full',         // className
-  true, true, true, // showMcpManager, showAiModelManager, showSystemContextEditor
-  true              // showAgentManager
-);
-
-export default function App() {
-  return aiChat.render();
+import React from 'react';
+import { ChatInterface, type Message, type Attachment } from '@leeoohoo/aichat';
+
+function App() {
+  const customRenderer = {
+    renderMessage: (message: Message) => (
+      <div className="custom-message">
+        {message.content}
+      </div>
+    ),
+    renderAttachment: (attachment: Attachment) => (
+      <div className="custom-attachment">
+        {attachment.name}
+      </div>
+    ),
+  };
+
+  return (
+    <ChatInterface customRenderer={customRenderer} />
+  );
 }
 ```
 
-常用导出 Common exports
+## 组件API
 
-- 组件 Components: `StandaloneChatInterface`, `ChatInterface`, `MessageList`, `InputArea`, `SessionList`, `ThemeToggle`, `McpManager`, `AiModelManager`, `SystemContextEditor`
-- Hooks: `useTheme`, `useChatStore`
-- 工具 Utils/API: `lib/api`, `lib/services`, `lib/utils`
-- 类型 Types: 从 `@leeoohoo/aichat` 导入类型 Import types from the package
+### ChatInterface
 
-## 环境与配置 Env & Config
+主要的聊天界面组件。
 
-前端 Frontend
+#### Props
 
-- 开发环境 dev: Vite 代理将 `/api` 指向 `http://localhost:3001`
-- 生产 prod: 通过 `apiBaseUrl`/`port` 或自行配置反向代理 Configure `apiBaseUrl`/`port` or reverse proxy
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `className` | `string` | - | 自定义CSS类名 |
+| `onMessageSend` | `(content: string, attachments?: Attachment[]) => void` | - | 消息发送回调 |
+| `onSessionChange` | `(sessionId: string) => void` | - | 会话切换回调 |
+| `customRenderer` | `CustomRenderer` | - | 自定义渲染器 |
 
-后端 Server (`server/chat_app_node_server`)
+### 其他组件
 
-- `.env`
+- `MessageList` - 消息列表组件
+- `InputArea` - 输入区域组件
+- `SessionList` - 会话列表组件
+- `ThemeToggle` - 主题切换组件
+- `McpManager` - MCP管理组件
+- `AiModelManager` - AI模型管理组件
 
-```env
-OPENAI_API_KEY=your_api_key
-OPENAI_BASE_URL=https://api.openai.com/v1
-PORT=3001
-NODE_ENV=development
-```
+## Hooks
 
-- 数据库 Database: 默认 SQLite，配置见 `server/chat_app_node_server/config/database.json`；可切换 MongoDB
+### useChatStore
 
-## API 概览 API Overview
+聊天状态管理Hook。
 
-- Sessions: `/api/sessions` CRUD, messages: `/api/sessions/:id/messages`
-- Agents: `/api/agents` CRUD, stream: `/api/agents/chat/stream`
-- MCP: `/api/mcp-configs` CRUD, profiles, resource reading
-- AI Model Configs: `/api/ai-model-configs` CRUD
-- System Contexts: `/api/system-contexts` CRUD, active context
-- Streaming chat: `/api/agent_v2/chat/stream` (SSE)
+```tsx
+import { useChatStore } from '@leeoohoo/aichat';
+
+function MyComponent() {
+  const {
+    currentSession,
+    messages,
+    isLoading,
+    sendMessage,
+    createSession,
+    switchSession,
+  } = useChatStore();
+
+  // 使用状态和方法
+}
+```
 
-详细见 See details: `server/chat_app_node_server/README.md`
+### useTheme
 
-## 示例 Examples
+主题管理Hook。
 
-- `examples/complete-example`: 完整示例（含 Electron） Complete sample (with Electron)
+```tsx
+import { useTheme } from '@leeoohoo/aichat';
 
-```bash
-cd examples/complete-example
-npm install
-npm run dev:full   # 前端 + 后端 Frontend + Server
+function MyComponent() {
+  const { theme, setTheme, actualTheme } = useTheme();
+
+  return (
+    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+      切换到 {theme === 'light' ? '暗色' : '亮色'} 主题
+    </button>
+  );
+}
 ```
 
-## 开发脚本 Scripts (root)
+## 配置
 
-- `npm run dev` Vite 本地预览 Local dev
-- `npm run build:lib` 构建库 Build library bundle
-- `npm run test`/`test:ui` 单测 Vitest
-- `npm run lint`/`lint:fix` ESLint
-- `npm run storybook` 组件调试 Storybook
+### 环境变量
 
-## 许可证 License
+在使用前，请确保设置以下环境变量：
 
-MIT
+```env
+# OpenAI配置
+VITE_OPENAI_API_KEY=your_openai_api_key
+VITE_OPENAI_BASE_URL=https://api.openai.com/v1
 
-—
+# 服务器配置
+VITE_API_BASE_URL=http://localhost:3001
+```
+
+### 数据库初始化
 
-如需更细的接入与排障，参见 Also see: `USAGE.md`, `INTEGRATION_EXAMPLE.md`, `MODULE_CONTROL.md`。
+```tsx
+import { initDatabase } from '@leeoohoo/aichat';
+
+// 在应用启动时初始化数据库
+initDatabase().then(() => {
+  console.log('数据库初始化完成');
+});
+```
 
 ## 样式定制
 
@@ -239,4 +274,4 @@ MIT
 
 ## 支持
 
-如果你觉得这个项目有用，请给它一个⭐️！
+如果你觉得这个项目有用，请给它一个⭐️！