366 lines
7.6 KiB
Markdown
366 lines
7.6 KiB
Markdown
# @ai-assistant/web
|
||
|
||
AI Terminal Assistant 的现代 Web 界面 - 基于 React、Vite 和 Tailwind CSS 构建。
|
||
|
||
## 📦 安装
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 启动开发服务器
|
||
pnpm dev
|
||
|
||
# 构建生产版本
|
||
pnpm build
|
||
```
|
||
|
||
## 🌟 功能特性
|
||
|
||
- **现代化界面** - 简洁、响应式界面，支持深色/浅色主题
|
||
- **实时对话** - 基于 WebSocket 的即时消息
|
||
- **代码编辑器** - 使用 Monaco Editor 的语法高亮
|
||
- **文件浏览器** - 浏览和编辑项目文件
|
||
- **终端集成** - 嵌入式终端执行命令
|
||
- **Markdown 渲染** - AI 响应的富文本格式
|
||
- **PWA 支持** - 可安装为桌面/移动应用
|
||
- **移动响应式** - 适配所有屏幕尺寸
|
||
- **键盘快捷键** - 高效导航和操作
|
||
|
||
## 🏗️ 架构
|
||
|
||
```
|
||
src/
|
||
├── components/
|
||
│ ├── Chat/ # 对话界面组件
|
||
│ │ ├── ChatWindow.tsx
|
||
│ │ ├── MessageList.tsx
|
||
│ │ ├── MessageInput.tsx
|
||
│ │ └── CodeBlock.tsx
|
||
│ ├── Editor/ # 代码编辑器组件
|
||
│ │ ├── MonacoEditor.tsx
|
||
│ │ └── EditorToolbar.tsx
|
||
│ ├── FileBrowser/ # 文件导航
|
||
│ │ ├── FileTree.tsx
|
||
│ │ └── FilePreview.tsx
|
||
│ ├── Terminal/ # 终端模拟器
|
||
│ │ └── XTerminal.tsx
|
||
│ ├── Layout/ # 布局组件
|
||
│ │ ├── Sidebar.tsx
|
||
│ │ ├── Header.tsx
|
||
│ │ └── Tabs.tsx
|
||
│ └── Common/ # 共享组件
|
||
│ ├── Button.tsx
|
||
│ ├── Modal.tsx
|
||
│ └── Loading.tsx
|
||
├── hooks/ # 自定义 React Hooks
|
||
│ ├── useChat.ts
|
||
│ ├── useWebSocket.ts
|
||
│ ├── useTheme.ts
|
||
│ └── useKeyboard.ts
|
||
├── services/ # API 和服务层
|
||
│ ├── api.ts
|
||
│ ├── websocket.ts
|
||
│ └── storage.ts
|
||
├── store/ # 状态管理
|
||
│ ├── chat.store.ts
|
||
│ ├── editor.store.ts
|
||
│ └── settings.store.ts
|
||
├── styles/ # 全局样式
|
||
│ └── index.css
|
||
├── types/ # TypeScript 定义
|
||
├── utils/ # 工具函数
|
||
├── App.tsx # 主应用组件
|
||
└── main.tsx # 入口文件
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 开发
|
||
|
||
```bash
|
||
# 启动开发服务器
|
||
pnpm dev
|
||
|
||
# 应用将在 http://localhost:5173 可用
|
||
# 热模块替换已启用，可即时更新
|
||
```
|
||
|
||
### 生产构建
|
||
|
||
```bash
|
||
# 创建优化构建
|
||
pnpm build
|
||
|
||
# 预览生产构建
|
||
pnpm preview
|
||
|
||
# 构建输出在 dist/ 目录
|
||
```
|
||
|
||
## 🎨 用户界面
|
||
|
||
### 主要功能
|
||
|
||
#### 对话界面
|
||
- **消息历史** - 可滚动的持久化对话历史
|
||
- **代码高亮** - 代码块语法高亮
|
||
- **文件附件** - 拖拽文件支持
|
||
- **消息操作** - 复制、编辑、重新生成响应
|
||
- **流式响应** - 实时 AI 响应流
|
||
|
||
#### 代码编辑器
|
||
- **Monaco 编辑器** - VS Code 的编辑器引擎
|
||
- **多文件标签** - 同时处理多个文件
|
||
- **语法高亮** - 100+ 语言支持
|
||
- **智能感知** - 代码补全和提示
|
||
- **差异视图** - 并排代码比较
|
||
|
||
#### 文件浏览器
|
||
- **树形视图** - 分层文件结构
|
||
- **快速操作** - 创建、重命名、删除文件
|
||
- **搜索** - 快速文件搜索，支持模糊匹配
|
||
- **预览** - 快速预览文件无需打开
|
||
- **右键菜单** - 右键操作
|
||
|
||
#### 终端
|
||
- **XTerm.js** - 完整终端模拟
|
||
- **命令历史** - 浏览之前的命令
|
||
- **复制/粘贴** - 标准剪贴板操作
|
||
- **主题** - 多种配色方案
|
||
|
||
## 🎯 组件示例
|
||
|
||
### 使用对话组件
|
||
|
||
```tsx
|
||
import { Chat } from '@ai-assistant/web/components';
|
||
|
||
function App() {
|
||
return (
|
||
<Chat
|
||
serverUrl="http://localhost:3000"
|
||
sessionId="my-session"
|
||
onMessage={(message) => console.log('新消息:', message)}
|
||
theme="dark"
|
||
/>
|
||
);
|
||
}
|
||
```
|
||
|
||
### 自定义 Hook 用法
|
||
|
||
```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('你好 AI！')}>
|
||
发送消息
|
||
</button>
|
||
</div>
|
||
);
|
||
}
|
||
```
|
||
|
||
## ⚙️ 配置
|
||
|
||
### 环境变量
|
||
|
||
创建 `.env` 文件：
|
||
|
||
```env
|
||
# API 配置
|
||
VITE_API_URL=http://localhost:3000
|
||
VITE_WS_URL=ws://localhost:3000
|
||
VITE_AUTH_TOKEN=your-token-here
|
||
|
||
# 功能开关
|
||
VITE_ENABLE_TERMINAL=true
|
||
VITE_ENABLE_FILE_BROWSER=true
|
||
VITE_ENABLE_CODE_EDITOR=true
|
||
|
||
# 主题
|
||
VITE_DEFAULT_THEME=dark
|
||
```
|
||
|
||
### 构建配置
|
||
|
||
`vite.config.ts`：
|
||
|
||
```typescript
|
||
export default defineConfig({
|
||
plugins: [react()],
|
||
server: {
|
||
port: 5173,
|
||
proxy: {
|
||
'/api': 'http://localhost:3000'
|
||
}
|
||
},
|
||
build: {
|
||
outDir: 'dist',
|
||
sourcemap: true,
|
||
minify: 'esbuild'
|
||
}
|
||
});
|
||
```
|
||
|
||
## 🎹 键盘快捷键
|
||
|
||
| 快捷键 | 操作 |
|
||
|----------|--------|
|
||
| `Ctrl/Cmd + Enter` | 发送消息 |
|
||
| `Ctrl/Cmd + K` | 清空对话 |
|
||
| `Ctrl/Cmd + /` | 切换侧边栏 |
|
||
| `Ctrl/Cmd + ,` | 打开设置 |
|
||
| `Ctrl/Cmd + Shift + P` | 命令面板 |
|
||
| `Ctrl/Cmd + B` | 切换文件浏览器 |
|
||
| `Ctrl/Cmd + J` | 切换终端 |
|
||
| `Esc` | 关闭模态框/弹窗 |
|
||
|
||
## 📱 渐进式 Web 应用
|
||
|
||
应用可以安装为 PWA：
|
||
|
||
1. 在 Chrome/Edge 中打开
|
||
2. 点击地址栏中的安装图标
|
||
3. 或使用浏览器菜单："安装应用"
|
||
|
||
功能：
|
||
- 使用 Service Worker 的离线支持
|
||
- 桌面/移动应用体验
|
||
- 推送通知（即将推出）
|
||
- 后台同步
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行单元测试
|
||
pnpm test
|
||
|
||
# 运行覆盖率测试
|
||
pnpm test:coverage
|
||
|
||
# 运行端到端测试
|
||
pnpm test:e2e
|
||
|
||
# 组件测试
|
||
pnpm test:components
|
||
```
|
||
|
||
### 测试示例
|
||
|
||
```tsx
|
||
import { render, screen } from '@testing-library/react';
|
||
import { Chat } from './Chat';
|
||
|
||
test('渲染对话界面', () => {
|
||
render(<Chat serverUrl="http://localhost:3000" />);
|
||
expect(screen.getByPlaceholderText('输入消息...')).toBeInTheDocument();
|
||
});
|
||
```
|
||
|
||
## 🎨 主题设置
|
||
|
||
### 自定义主题
|
||
|
||
```css
|
||
/* src/styles/themes/custom.css */
|
||
:root[data-theme="custom"] {
|
||
--primary: #6366f1;
|
||
--background: #0f172a;
|
||
--foreground: #f8fafc;
|
||
--border: #334155;
|
||
--accent: #8b5cf6;
|
||
}
|
||
```
|
||
|
||
### 应用主题
|
||
|
||
```tsx
|
||
import { useTheme } from '@ai-assistant/web/hooks';
|
||
|
||
function ThemeToggle() {
|
||
const { theme, setTheme } = useTheme();
|
||
|
||
return (
|
||
<button onClick={() => setTheme('custom')}>
|
||
使用自定义主题
|
||
</button>
|
||
);
|
||
}
|
||
```
|
||
|
||
## 📊 性能优化
|
||
|
||
### 优化技巧
|
||
|
||
1. **代码分割** - 路由懒加载
|
||
2. **图片优化** - WebP 格式带后备方案
|
||
3. **包大小** - 启用 Tree Shaking
|
||
4. **缓存** - Service Worker 缓存
|
||
5. **虚拟滚动** - 长列表优化
|
||
|
||
### 包分析
|
||
|
||
```bash
|
||
# 分析包大小
|
||
pnpm build:analyze
|
||
|
||
# 在浏览器中打开可视化
|
||
```
|
||
|
||
## 🚀 部署
|
||
|
||
### Vercel
|
||
|
||
```bash
|
||
# 部署到 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
|
||
```
|
||
|
||
### 静态托管
|
||
|
||
`dist/` 中的构建输出可由任何静态主机服务：
|
||
- Netlify
|
||
- GitHub Pages
|
||
- CloudFlare Pages
|
||
- AWS S3 + CloudFront
|
||
|
||
## 🤝 贡献
|
||
|
||
请查看主仓库的贡献指南了解详情。
|
||
|
||
## 📄 许可证
|
||
|
||
MIT 许可证 - 查看 [LICENSE](../../LICENSE) 了解详情。
|
||
|
||
## 🔗 链接
|
||
|
||
- [主仓库](https://github.com/username/ai-terminal-assistant)
|
||
- [组件 Storybook](https://storybook.example.com)
|
||
- [设计系统](https://design.example.com) |