@leeoohoo/aichat 1.0.8 → 1.0.10

package/README.md

@@ -1,214 +1,179 @@
 # @leeoohoo/aichat
 
-一个功能完整的React AI聊天组件，支持会话管理、MCP集成和SQLite持久化存储。
+React AI Chat Component and Node server. Bilingual README (中文/English).
 
-## 特性
+—
 
-- 🚀 **开箱即用** - 一个标签即可使用完整的AI聊天功能
-- 💬 **会话管理** - 支持多会话切换、创建、删除和重命名
-- 🤖 **AI模型支持** - 支持OpenAI GPT系列模型
-- 🔧 **MCP集成** - 支持Model Context Protocol工具调用
-- 💾 **数据持久化** - 基于SQLite的本地数据存储
-- 🎨 **主题切换** - 支持明暗主题切换
-- 📱 **响应式设计** - 适配各种屏幕尺寸
-- 🔒 **类型安全** - 完整的TypeScript类型定义
+一个功能完整的 React AI 聊天组件库，配套 Node 后端服务，支持会话管理、MCP 工具集成与持久化存储。
 
-## 🚀 快速开始
+## 功能 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
 
-```bash
-# 使用 npm 
-npm install @leeoohoo/aichat
-
-# 或使用 yarn 
-yarn add @leeoohoo/aichat
+## 代码结构 Repository Structure
 
-# 或使用 pnpm 
-pnpm add @leeoohoo/aichat
-```
+- 根目录 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
 
-组件需要后端API服务支持，请先启动后端服务：
+1) 作为依赖使用 Use as a dependency
 
 ```bash
-# 方式一：使用npm脚本启动
-npx @leeoohoo/aichat start:server
-
-# 方式二：直接运行服务器文件
-node node_modules/@leeoohoo/aichat/server/index.js
+npm install @leeoohoo/aichat
+# or
+yarn add @leeoohoo/aichat
+# or
+pnpm add @leeoohoo/aichat
 ```
 
-后端服务默认运行在 `http://localhost:3001`，提供以下API：
-- 会话管理 (`/api/sessions`)
-- 消息管理 (`/api/messages`) 
-- MCP配置 (`/api/mcp-configs`)
-- AI模型配置 (`/api/ai-model-configs`)
-- 系统上下文 (`/api/system-context`)
-
-### 基础使用（推荐）
-
-使用独立聊天组件，无需任何配置，开箱即用：
+最简用法 Minimal usage
 
 ```tsx
-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 function App() {
+  return <StandaloneChatInterface className="h-screen" />;
 }
+```
+
+2) 本仓库本地开发 Run locally (this repo)
 
-export default App;
+- 启动后端 Start the API server
+
+```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
 ```
 
-## 高级配置
+- 启动前端 Start the frontend demo
 
-### 自定义事件处理
+```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
-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}
-    />
-  );
-}
+<StandaloneChatInterface apiBaseUrl="https://your.domain/api" />
+// or
+<StandaloneChatInterface port={3001} />
 ```
 
-### 自定义渲染器
+## 使用 Usage
+
+推荐 Recommended: 独立组件 Standalone component
 
 ```tsx
-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} />
-  );
-}
-```
+import StandaloneChatInterface from '@leeoohoo/aichat';
+import '@leeoohoo/aichat/styles';
 
-## 组件API
+<StandaloneChatInterface
+  className="h-full"
+  userId="user_123"
+  projectId="proj_456"
+  showMcpManager
+  showAiModelManager
+  showSystemContextEditor
+  showAgentManager
+/>
+```
 
-### ChatInterface
+可选：类方式 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();
+}
+```
 
-#### Props
+常用导出 Common exports
 
-| 属性 | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| `className` | `string` | - | 自定义CSS类名 |
-| `onMessageSend` | `(content: string, attachments?: Attachment[]) => void` | - | 消息发送回调 |
-| `onSessionChange` | `(sessionId: string) => void` | - | 会话切换回调 |
-| `customRenderer` | `CustomRenderer` | - | 自定义渲染器 |
+- 组件 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
 
-### 其他组件
+## 环境与配置 Env & Config
 
-- `MessageList` - 消息列表组件
-- `InputArea` - 输入区域组件
-- `SessionList` - 会话列表组件
-- `ThemeToggle` - 主题切换组件
-- `McpManager` - MCP管理组件
-- `AiModelManager` - AI模型管理组件
+前端 Frontend
 
-## Hooks
+- 开发环境 dev: Vite 代理将 `/api` 指向 `http://localhost:3001`
+- 生产 prod: 通过 `apiBaseUrl`/`port` 或自行配置反向代理 Configure `apiBaseUrl`/`port` or reverse proxy
 
-### useChatStore
+后端 Server (`server/chat_app_node_server`)
 
-聊天状态管理Hook。
+- `.env`
 
-```tsx
-import { useChatStore } from '@leeoohoo/aichat';
-
-function MyComponent() {
-  const {
-    currentSession,
-    messages,
-    isLoading,
-    sendMessage,
-    createSession,
-    switchSession,
-  } = useChatStore();
-
-  // 使用状态和方法
-}
+```env
+OPENAI_API_KEY=your_api_key
+OPENAI_BASE_URL=https://api.openai.com/v1
+PORT=3001
+NODE_ENV=development
 ```
 
-### useTheme
+- 数据库 Database: 默认 SQLite，配置见 `server/chat_app_node_server/config/database.json`；可切换 MongoDB
 
-主题管理Hook。
+## API 概览 API Overview
 
-```tsx
-import { useTheme } from '@leeoohoo/aichat';
+- 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)
 
-function MyComponent() {
-  const { theme, setTheme, actualTheme } = useTheme();
+详细见 See details: `server/chat_app_node_server/README.md`
 
-  return (
-    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
-      切换到 {theme === 'light' ? '暗色' : '亮色'} 主题
-    </button>
-  );
-}
-```
+## 示例 Examples
 
-## 配置
+- `examples/complete-example`: 完整示例（含 Electron） Complete sample (with Electron)
 
-### 环境变量
+```bash
+cd examples/complete-example
+npm install
+npm run dev:full   # 前端 + 后端 Frontend + Server
+```
 
-在使用前，请确保设置以下环境变量：
+## 开发脚本 Scripts (root)
 
-```env
-# OpenAI配置
-VITE_OPENAI_API_KEY=your_openai_api_key
-VITE_OPENAI_BASE_URL=https://api.openai.com/v1
+- `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
 
-# 服务器配置
-VITE_API_BASE_URL=http://localhost:3001
-```
+## 许可证 License
 
-### 数据库初始化
+MIT
 
-```tsx
-import { initDatabase } from '@leeoohoo/aichat';
+—
 
-// 在应用启动时初始化数据库
-initDatabase().then(() => {
-  console.log('数据库初始化完成');
-});
-```
+如需更细的接入与排障，参见 Also see: `USAGE.md`, `INTEGRATION_EXAMPLE.md`, `MODULE_CONTROL.md`。
 
 ## 样式定制
 
@@ -274,4 +239,4 @@ MIT
 
 ## 支持
 
-如果你觉得这个项目有用，请给它一个⭐️！
+如果你觉得这个项目有用，请给它一个⭐️！