docs: 添加中文文档
This commit is contained in:
@@ -0,0 +1,366 @@
|
||||
# @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)
|
||||
Reference in New Issue
Block a user