249 lines
8.9 KiB
Markdown
249 lines
8.9 KiB
Markdown
# XSH Assistant 编码指南
|
||
|
||
## 项目概览
|
||
|
||
**xsh-assistant** 是一个基于 Nuxt 3 的 AI 驱动内容生成平台，专注于数字内容创作（微课视频、虚拟讲师、绿幕合成等）。核心特性：
|
||
|
||
- **前端框架**: Nuxt 3 + Vue 3 + TypeScript + Tailwind CSS + Radix Vue UI
|
||
- **状态管理**: Pinia（带持久化）
|
||
- **媒体处理**: FFmpeg WASM（客户端视频处理）、WebAV（视频剪辑）
|
||
- **API 集成**: 统一的 `useFetchWrapped` 包装器，所有请求都通过 `API_BASE` 代理（`https://service1.fenshenzhike.com/`）
|
||
- **部署模式**: SPA（SSR=false）
|
||
|
||
## 核心架构模式
|
||
|
||
### 1. Composables 设计（Pinia + 自定义 Composables）
|
||
|
||
**状态管理采用分层设计**：
|
||
|
||
```
|
||
Pinia Stores（持久化状态）
|
||
├── useLoginState: 用户认证、token、个人资料
|
||
├── useHistory: AIGC 会话、聊天历史
|
||
└── useTourState: 新手引导状态
|
||
|
||
业务 Composables（无状态或短生命周期）
|
||
├── useFetchWrapped: API 请求包装（自动添加 token、user_id）
|
||
├── useLLM: LLM API 调用（Spark 模型集成）
|
||
├── useFFmpeg: FFmpeg WASM 单例管理
|
||
├── useVideoBackgroundCompositing: 视频合成（数字人+背景）
|
||
├── useVideoSubtitleEmbedding: 字幕嵌入
|
||
└── useDownload: 文件下载管理
|
||
```
|
||
|
||
**关键模式**：
|
||
|
||
- **Pinia stores 必须是单一实例**，通过 `storeToRefs()` 获取响应式引用
|
||
- **API 请求必须通过 `useFetchWrapped`** 来自动处理认证头（token/user_id）
|
||
- **FFmpeg 采用单例模式**（`useFFmpeg()` 返回全局加载的实例），避免重复初始化
|
||
|
||
### 2. API 请求模式
|
||
|
||
所有 API 请求使用统一的 `useFetchWrapped` 包装器：
|
||
|
||
```typescript
|
||
// 基础签名
|
||
useFetchWrapped<RequestType, ResponseType>(action: string, payload?: RequestType, options?: FetchOptions)
|
||
|
||
// 请求格式示例（来自 useHistory）
|
||
useFetchWrapped<AuthedRequest, BaseResponse<resp.xxx>>(
|
||
'App.User_User.CheckSession', // action 作为查询参数 ?s=
|
||
{ token: loginState.token, user_id: loginState.user.id, ...payload },
|
||
{ method: 'POST' } // 默认 POST
|
||
)
|
||
```
|
||
|
||
**约定**：
|
||
|
||
- **每个请求必须包含** `token` 和 `user_id`（来自 `useLoginState`）
|
||
- **响应结构统一**: `BaseResponse<T>` 包含 `ret: number` 状态码和 `data: T` 数据
|
||
- **API_BASE 在 `nuxt.config.ts` 中定义**，所有请求都相对于此 URL
|
||
|
||
### 3. 媒体处理架构
|
||
|
||
#### FFmpeg 初始化流程
|
||
|
||
- **单例加载**: 首次调用 `useFFmpeg()` 时初始化，后续复用缓存的实例
|
||
- **WASM 资源加载**: 从 CDN（`cdn.jsdelivr.net`）加载 FFmpeg core、wasm、worker
|
||
- **错误恢复**: 调用 `cleanupFFmpeg()` 清理资源并重置单例
|
||
|
||
#### 视频合成流程（核心用例）
|
||
|
||
```
|
||
输入: 透明通道视频 (WebM) + 背景图 (PNG/File)
|
||
↓
|
||
1. 获取背景图尺寸
|
||
2. 计算等比缩放到 720P
|
||
3. 加载文件到 FFmpeg vFS
|
||
4. 执行 FFmpeg 滤镜链：
|
||
- 背景: scale → ${outputWidth}x${outputHeight}
|
||
- 视频: scale → ${outputWidth}x${outputHeight} (保留 alpha)
|
||
- overlay: 视频叠加到背景（format=auto）
|
||
5. 使用 VP9 编码（支持 alpha）+ Opus 音频编码
|
||
6. 返回 Blob → 可直接上传或本地预览
|
||
```
|
||
|
||
### 4. UI 组件架构
|
||
|
||
#### 内置组件库（`components/uni/`）
|
||
|
||
自定义包装组件，提供统一 API：
|
||
|
||
- `UniButton`: 按钮 + loading 状态
|
||
- `UniInput`/`UniTextArea`: 表单输入
|
||
- `UniSelect`: 下拉选择
|
||
- `UniMessage`: 全局消息通知（通过 provide/inject）
|
||
- `UniCopyable`: 可复制文本
|
||
|
||
**消息通知用法**：
|
||
|
||
```typescript
|
||
const toast = useToast() // Radix Vue 的 Toast（顶部通知）
|
||
// 或从 provide 注入
|
||
const messageApi = inject('uni-message')
|
||
messageApi.success('操作成功')
|
||
messageApi.error('操作失败', 5000)
|
||
```
|
||
|
||
#### Radix Vue + Nuxt UI 集成
|
||
|
||
- 使用 Radix Vue for 基础组件（button, dialog, select）
|
||
- Nuxt UI 用于高级组件 + 主题管理
|
||
- **颜色方案**: primary='indigo', gray='neutral'，详见 `app.config.ts`
|
||
|
||
### 5. 路由与页面结构
|
||
|
||
**目录映射**：
|
||
|
||
```
|
||
pages/
|
||
├── generation.vue (导航枢纽)
|
||
└── aigc/
|
||
├── chat/index.vue (聊天页，支持多 LLM 模型)
|
||
├── draw/index.vue (绘图生成)
|
||
└── generation/
|
||
├── course.vue (微课生成)
|
||
├── green-screen.vue (绿幕视频)
|
||
├── avatar-models.vue (数字讲师)
|
||
├── materials.vue (片头片尾)
|
||
├── ppt-templates.vue (PPT 库)
|
||
└── admin/ (管理功能)
|
||
```
|
||
|
||
**导航约定**：
|
||
|
||
- `/generation` → 功能导航页面
|
||
- `/aigc/chat` → 聊天/文本生成
|
||
- `/generation/course` → 视频生成工作流
|
||
- 所有生成功能都需要登录（ModalAuthentication 处理）
|
||
|
||
## 开发工作流
|
||
|
||
### 启动项目
|
||
|
||
```bash
|
||
ni # 安装依赖
|
||
nr dev # 启动 http://localhost:3000
|
||
nr generate # 生产构建 (生成静态文件)
|
||
```
|
||
|
||
### 常见任务
|
||
|
||
**添加新的 API 端点**：
|
||
|
||
1. 定义 Request 和 Response 类型（参考 `typings/llm.ts`）
|
||
2. 在 composable 中使用 `useFetchWrapped` 调用
|
||
3. 自动包含 token/user_id（来自 `useLoginState`）
|
||
|
||
**添加新的视频处理功能**：
|
||
|
||
1. 使用 `useFFmpeg()` 获取实例（自动初始化）
|
||
2. 写入文件到 vFS: `ffmpeg.writeFile()`
|
||
3. 执行命令：`ffmpeg.exec([...filterArgs])`
|
||
4. 清理临时文件：`ffmpeg.deleteFile()`
|
||
5. 使用 progress callback 通报处理进度
|
||
|
||
**添加新的 UI 组件**：
|
||
|
||
1. 创建在 `components/` 下（自动注册）
|
||
2. 优先使用 Radix Vue + Nuxt UI（已集成）
|
||
3. 使用 Tailwind CSS utility classes + `@apply` 指令
|
||
4. 通过 `app.config.ts` 自定义 UI 主题
|
||
|
||
## 项目特定的约定
|
||
|
||
### 类型定义位置
|
||
|
||
- **LLM 相关**: `typings/llm.ts`（ChatMessage, ChatSession, ModelTag, LLMModal）
|
||
- **全局类型**: `typings/types.d.ts`（BaseResponse, AuthedRequest, UserSchema）
|
||
- **组件接口**: 组件目录下的 `index.d.ts`（例 `components/aigc/drawing/index.d.ts`）
|
||
|
||
### 命名规范
|
||
|
||
- **Composables**: `use` 前缀（`useLoginState`, `useLLM`）
|
||
- **Stores**: `use` + 功能名（`useHistory`, `useTourState`）
|
||
- **组件**: PascalCase（`ChatItem.vue`, `ModalAuthentication.vue`）
|
||
- **工具函数**: camelCase，放在 `composables/` 或各功能目录
|
||
|
||
### 响应式数据模式
|
||
|
||
- **Pinia store 返回值**: 必须通过 `storeToRefs()` 才能保持响应式
|
||
- **模板中的 ref**: 直接访问（Vue 自动展开）
|
||
- **跨组件数据**: 优先使用 Pinia store（带持久化）
|
||
|
||
### 进度反馈与错误处理
|
||
|
||
- **长时间操作** (视频处理): 通过 callback 函数报告 progress（0-100）
|
||
- **错误处理**: 返回 Promise reject，上层 catch 处理；可选通过 toast/message 提示
|
||
- **FFmpeg 错误**: 捕获 exitCode 非零，记录详细的 FFmpeg 输出
|
||
|
||
## 依赖与性能优化
|
||
|
||
### 关键依赖
|
||
|
||
- **@ffmpeg/ffmpeg@0.12.15**: WASM 视频处理（从 CDN 加载）
|
||
- **@webav/av-cliper**: 客户端视频剪辑库
|
||
- **markdown-it + highlight.js**: 内容渲染（支持代码高亮）
|
||
- **date-fns/dayjs**: 时间处理（dayjs-nuxt 提供全局实例）
|
||
- **idb-keyval**: IndexedDB 简化操作（缓存大文件）
|
||
|
||
### Vite 优化设置
|
||
|
||
```typescript
|
||
// nuxt.config.ts 中排除以下包进行优化，避免 bundling WASM
|
||
optimizeDeps.exclude: ['@ffmpeg/ffmpeg', 'idb-keyval', '@webav/av-cliper', 'gsap', 'markdown-it']
|
||
```
|
||
|
||
### 构建排除项
|
||
|
||
Worker 格式设置为 ES Module，避免 Vite 默认处理：
|
||
|
||
```typescript
|
||
vite.worker.format = 'es'
|
||
```
|
||
|
||
## 测试与调试
|
||
|
||
- **开发服务器日志**: 浏览器控制台查看 FFmpeg、API、业务日志
|
||
- **FFmpeg 调试**: `[FFmpeg]` 前缀的日志输出包含加载进度、命令执行信息
|
||
- **状态调试**: Pinia DevTools（启用 `devtools: true`）
|
||
- **样式调试**: Tailwind 配置在 `tailwind.config.ts`，按需自定义
|
||
|
||
## 常见陷阱与解决方案
|
||
|
||
| 问题 | 原因 | 解决方案 |
|
||
| ------------------ | ------------------- | --------------------------------------------------------------- |
|
||
| API 请求 401 | 缺少 token 或已过期 | 检查 `useLoginState().token`，通过 ModalAuthentication 重新登录 |
|
||
| FFmpeg 加载超时 | CDN 资源加载慢 | 检查网络，可切换到本地 `/public/assets/ffmpeg` |
|
||
| 视频输出无声音 | 滤镜链未映射音频 | 确保 FFmpeg 命令包含 `-map '1:a?'` 映射音频轨道 |
|
||
| 组件未注册 | 文件位置错误 | 确保在 `components/` 目录下，子目录自动扁平化注册 |
|
||
| Pinia 状态未持久化 | 未配置 persist 选项 | 在 store 返回语句后添加 persist 配置（参考 `useLoginState`） |
|
||
|
||
## 资源链接
|
||
|
||
- [Nuxt 3 文档](https://nuxt.com/docs)
|
||
- [Pinia 文档](https://pinia.vuejs.org)
|
||
- [FFmpeg.wasm 文档](https://ffmpegwasm.netlify.app/)
|
||
- [Radix Vue](https://www.radix-vue.com/)
|
||
- [Nuxt UI 组件库](https://ui.nuxt.com/)：可使用 nuxt-ui MCP 工具
|