docs: 更新项目文档
This commit is contained in:
@@ -0,0 +1,366 @@
|
||||
# @ai-assistant/web
|
||||
|
||||
Modern web interface for AI Terminal Assistant - built with React, Vite, and Tailwind CSS.
|
||||
|
||||
## 📦 Installation
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Start development server
|
||||
pnpm dev
|
||||
|
||||
# Build for production
|
||||
pnpm build
|
||||
```
|
||||
|
||||
## 🌟 Features
|
||||
|
||||
- **Modern UI** - Clean, responsive interface with dark/light themes
|
||||
- **Real-time Chat** - WebSocket-based instant messaging
|
||||
- **Code Editor** - Syntax highlighting with Monaco Editor
|
||||
- **File Browser** - Browse and edit project files
|
||||
- **Terminal Integration** - Embedded terminal for command execution
|
||||
- **Markdown Rendering** - Rich text formatting for AI responses
|
||||
- **PWA Support** - Install as desktop/mobile app
|
||||
- **Mobile Responsive** - Optimized for all screen sizes
|
||||
- **Keyboard Shortcuts** - Efficient navigation and actions
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
├── components/
|
||||
│ ├── Chat/ # Chat interface components
|
||||
│ │ ├── ChatWindow.tsx
|
||||
│ │ ├── MessageList.tsx
|
||||
│ │ ├── MessageInput.tsx
|
||||
│ │ └── CodeBlock.tsx
|
||||
│ ├── Editor/ # Code editor components
|
||||
│ │ ├── MonacoEditor.tsx
|
||||
│ │ └── EditorToolbar.tsx
|
||||
│ ├── FileBrowser/ # File navigation
|
||||
│ │ ├── FileTree.tsx
|
||||
│ │ └── FilePreview.tsx
|
||||
│ ├── Terminal/ # Terminal emulator
|
||||
│ │ └── XTerminal.tsx
|
||||
│ ├── Layout/ # Layout components
|
||||
│ │ ├── Sidebar.tsx
|
||||
│ │ ├── Header.tsx
|
||||
│ │ └── Tabs.tsx
|
||||
│ └── Common/ # Shared components
|
||||
│ ├── Button.tsx
|
||||
│ ├── Modal.tsx
|
||||
│ └── Loading.tsx
|
||||
├── hooks/ # Custom React hooks
|
||||
│ ├── useChat.ts
|
||||
│ ├── useWebSocket.ts
|
||||
│ ├── useTheme.ts
|
||||
│ └── useKeyboard.ts
|
||||
├── services/ # API and service layer
|
||||
│ ├── api.ts
|
||||
│ ├── websocket.ts
|
||||
│ └── storage.ts
|
||||
├── store/ # State management
|
||||
│ ├── chat.store.ts
|
||||
│ ├── editor.store.ts
|
||||
│ └── settings.store.ts
|
||||
├── styles/ # Global styles
|
||||
│ └── index.css
|
||||
├── types/ # TypeScript definitions
|
||||
├── utils/ # Utility functions
|
||||
├── App.tsx # Main app component
|
||||
└── main.tsx # Entry point
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
# Start development server
|
||||
pnpm dev
|
||||
|
||||
# The app will be available at http://localhost:5173
|
||||
# Hot module replacement is enabled for instant updates
|
||||
```
|
||||
|
||||
### Production Build
|
||||
|
||||
```bash
|
||||
# Create optimized build
|
||||
pnpm build
|
||||
|
||||
# Preview production build
|
||||
pnpm preview
|
||||
|
||||
# Build output in dist/ directory
|
||||
```
|
||||
|
||||
## 🎨 User Interface
|
||||
|
||||
### Main Features
|
||||
|
||||
#### Chat Interface
|
||||
- **Message History** - Scrollable chat with persistent history
|
||||
- **Code Highlighting** - Syntax highlighting for code blocks
|
||||
- **File Attachments** - Drag & drop file support
|
||||
- **Message Actions** - Copy, edit, regenerate responses
|
||||
- **Streaming Responses** - Real-time AI response streaming
|
||||
|
||||
#### Code Editor
|
||||
- **Monaco Editor** - VS Code's editor engine
|
||||
- **Multi-file Tabs** - Work with multiple files
|
||||
- **Syntax Highlighting** - 100+ language support
|
||||
- **IntelliSense** - Code completion and hints
|
||||
- **Diff View** - Side-by-side code comparison
|
||||
|
||||
#### File Browser
|
||||
- **Tree View** - Hierarchical file structure
|
||||
- **Quick Actions** - Create, rename, delete files
|
||||
- **Search** - Fast file search with fuzzy matching
|
||||
- **Preview** - Quick file preview without opening
|
||||
- **Context Menu** - Right-click actions
|
||||
|
||||
#### Terminal
|
||||
- **XTerm.js** - Full terminal emulation
|
||||
- **Command History** - Navigate previous commands
|
||||
- **Copy/Paste** - Standard clipboard operations
|
||||
- **Themes** - Multiple color schemes
|
||||
|
||||
## 🎯 Component Examples
|
||||
|
||||
### Using the Chat Component
|
||||
|
||||
```tsx
|
||||
import { Chat } from '@ai-assistant/web/components';
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<Chat
|
||||
serverUrl="http://localhost:3000"
|
||||
sessionId="my-session"
|
||||
onMessage={(message) => console.log('New message:', message)}
|
||||
theme="dark"
|
||||
/>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Hook Usage
|
||||
|
||||
```tsx
|
||||
import { useChat } from '@ai-assistant/web/hooks';
|
||||
|
||||
function MyComponent() {
|
||||
const { messages, sendMessage, isLoading } = useChat({
|
||||
serverUrl: 'http://localhost:3000',
|
||||
sessionId: 'my-session'
|
||||
});
|
||||
|
||||
return (
|
||||
<div>
|
||||
{messages.map(msg => (
|
||||
<div key={msg.id}>{msg.content}</div>
|
||||
))}
|
||||
<button onClick={() => sendMessage('Hello AI!')}>
|
||||
Send Message
|
||||
</button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create `.env` file:
|
||||
|
||||
```env
|
||||
# API Configuration
|
||||
VITE_API_URL=http://localhost:3000
|
||||
VITE_WS_URL=ws://localhost:3000
|
||||
VITE_AUTH_TOKEN=your-token-here
|
||||
|
||||
# Feature Flags
|
||||
VITE_ENABLE_TERMINAL=true
|
||||
VITE_ENABLE_FILE_BROWSER=true
|
||||
VITE_ENABLE_CODE_EDITOR=true
|
||||
|
||||
# Theme
|
||||
VITE_DEFAULT_THEME=dark
|
||||
```
|
||||
|
||||
### Build Configuration
|
||||
|
||||
`vite.config.ts`:
|
||||
|
||||
```typescript
|
||||
export default defineConfig({
|
||||
plugins: [react()],
|
||||
server: {
|
||||
port: 5173,
|
||||
proxy: {
|
||||
'/api': 'http://localhost:3000'
|
||||
}
|
||||
},
|
||||
build: {
|
||||
outDir: 'dist',
|
||||
sourcemap: true,
|
||||
minify: 'esbuild'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
## 🎹 Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Ctrl/Cmd + Enter` | Send message |
|
||||
| `Ctrl/Cmd + K` | Clear chat |
|
||||
| `Ctrl/Cmd + /` | Toggle sidebar |
|
||||
| `Ctrl/Cmd + ,` | Open settings |
|
||||
| `Ctrl/Cmd + Shift + P` | Command palette |
|
||||
| `Ctrl/Cmd + B` | Toggle file browser |
|
||||
| `Ctrl/Cmd + J` | Toggle terminal |
|
||||
| `Esc` | Close modal/popup |
|
||||
|
||||
## 📱 Progressive Web App
|
||||
|
||||
The app can be installed as a PWA:
|
||||
|
||||
1. Open in Chrome/Edge
|
||||
2. Click install icon in address bar
|
||||
3. Or use browser menu: "Install App"
|
||||
|
||||
Features:
|
||||
- Offline support with service worker
|
||||
- Desktop/mobile app experience
|
||||
- Push notifications (coming soon)
|
||||
- Background sync
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
```bash
|
||||
# Run unit tests
|
||||
pnpm test
|
||||
|
||||
# Run with coverage
|
||||
pnpm test:coverage
|
||||
|
||||
# Run E2E tests
|
||||
pnpm test:e2e
|
||||
|
||||
# Component testing
|
||||
pnpm test:components
|
||||
```
|
||||
|
||||
### Testing Examples
|
||||
|
||||
```tsx
|
||||
import { render, screen } from '@testing-library/react';
|
||||
import { Chat } from './Chat';
|
||||
|
||||
test('renders chat interface', () => {
|
||||
render(<Chat serverUrl="http://localhost:3000" />);
|
||||
expect(screen.getByPlaceholderText('Type a message...')).toBeInTheDocument();
|
||||
});
|
||||
```
|
||||
|
||||
## 🎨 Theming
|
||||
|
||||
### Custom Theme
|
||||
|
||||
```css
|
||||
/* src/styles/themes/custom.css */
|
||||
:root[data-theme="custom"] {
|
||||
--primary: #6366f1;
|
||||
--background: #0f172a;
|
||||
--foreground: #f8fafc;
|
||||
--border: #334155;
|
||||
--accent: #8b5cf6;
|
||||
}
|
||||
```
|
||||
|
||||
### Apply Theme
|
||||
|
||||
```tsx
|
||||
import { useTheme } from '@ai-assistant/web/hooks';
|
||||
|
||||
function ThemeToggle() {
|
||||
const { theme, setTheme } = useTheme();
|
||||
|
||||
return (
|
||||
<button onClick={() => setTheme('custom')}>
|
||||
Use Custom Theme
|
||||
</button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 Performance
|
||||
|
||||
### Optimization Tips
|
||||
|
||||
1. **Code Splitting** - Routes are lazy loaded
|
||||
2. **Image Optimization** - WebP with fallbacks
|
||||
3. **Bundle Size** - Tree shaking enabled
|
||||
4. **Caching** - Service worker caching
|
||||
5. **Virtual Scrolling** - For long lists
|
||||
|
||||
### Bundle Analysis
|
||||
|
||||
```bash
|
||||
# Analyze bundle size
|
||||
pnpm build:analyze
|
||||
|
||||
# Opens visualization in browser
|
||||
```
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### Vercel
|
||||
|
||||
```bash
|
||||
# Deploy to Vercel
|
||||
vercel deploy --prod
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
```dockerfile
|
||||
FROM node:20-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
FROM nginx:alpine
|
||||
COPY --from=builder /app/dist /usr/share/nginx/html
|
||||
EXPOSE 80
|
||||
```
|
||||
|
||||
### Static Hosting
|
||||
|
||||
Build output in `dist/` can be served by any static host:
|
||||
- Netlify
|
||||
- GitHub Pages
|
||||
- CloudFlare Pages
|
||||
- AWS S3 + CloudFront
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
See the main repository's contributing guide for details.
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see [LICENSE](../../LICENSE) for details.
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- [Main Repository](https://github.com/username/ai-terminal-assistant)
|
||||
- [Component Storybook](https://storybook.example.com)
|
||||
- [Design System](https://design.example.com)
|
||||
Reference in New Issue
Block a user