kurihada/ai-terminal-assistant

Fork 0

Files

T

kurihada 563224fa73 docs: 添加中文文档

2025-12-12 15:31:38 +08:00

7.6 KiB

Raw Blame History

@ai-assistant/web

AI Terminal Assistant 的现代 Web 界面 - 基于 React、Vite 和 Tailwind CSS 构建。

📦 安装

# 安装依赖
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              # 入口文件

🚀 快速开始

开发

# 启动开发服务器
pnpm dev

# 应用将在 http://localhost:5173 可用
# 热模块替换已启用，可即时更新

生产构建

# 创建优化构建
pnpm build

# 预览生产构建
pnpm preview

# 构建输出在 dist/ 目录

🎨 用户界面

主要功能

对话界面

消息历史 - 可滚动的持久化对话历史
代码高亮 - 代码块语法高亮
文件附件 - 拖拽文件支持
消息操作 - 复制、编辑、重新生成响应
流式响应 - 实时 AI 响应流

代码编辑器

Monaco 编辑器 - VS Code 的编辑器引擎
多文件标签 - 同时处理多个文件
语法高亮 - 100+ 语言支持
智能感知 - 代码补全和提示
差异视图 - 并排代码比较

文件浏览器

树形视图 - 分层文件结构
快速操作 - 创建、重命名、删除文件
搜索 - 快速文件搜索，支持模糊匹配
预览 - 快速预览文件无需打开
右键菜单 - 右键操作

终端

XTerm.js - 完整终端模拟
命令历史 - 浏览之前的命令
复制/粘贴 - 标准剪贴板操作
主题 - 多种配色方案

🎯 组件示例

使用对话组件

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 用法

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 文件：

# 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：

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：

在 Chrome/Edge 中打开
点击地址栏中的安装图标
或使用浏览器菜单："安装应用"

功能：

使用 Service Worker 的离线支持
桌面/移动应用体验
推送通知（即将推出）
后台同步

🧪 测试

# 运行单元测试
pnpm test

# 运行覆盖率测试
pnpm test:coverage

# 运行端到端测试
pnpm test:e2e

# 组件测试
pnpm test:components

测试示例

import { render, screen } from '@testing-library/react';
import { Chat } from './Chat';

test('渲染对话界面', () => {
  render(<Chat serverUrl="http://localhost:3000" />);
  expect(screen.getByPlaceholderText('输入消息...')).toBeInTheDocument();
});

🎨 主题设置

自定义主题

/* src/styles/themes/custom.css */
:root[data-theme="custom"] {
  --primary: #6366f1;
  --background: #0f172a;
  --foreground: #f8fafc;
  --border: #334155;
  --accent: #8b5cf6;
}

应用主题

import { useTheme } from '@ai-assistant/web/hooks';

function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme('custom')}>
      使用自定义主题
    </button>
  );
}

📊 性能优化

优化技巧

代码分割 - 路由懒加载
图片优化 - WebP 格式带后备方案
包大小 - 启用 Tree Shaking
缓存 - Service Worker 缓存
虚拟滚动 - 长列表优化

包分析

# 分析包大小
pnpm build:analyze

# 在浏览器中打开可视化

🚀 部署

Vercel

# 部署到 Vercel
vercel deploy --prod

Docker

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 了解详情。

7.6 KiB Raw Blame History Unescape Escape