# @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)