一、接入的功能模块
1. AI 对话功能
- 功能描述：基于 DeepSeek API 的智能对话助手
- 技术实现：
- 后端：
/api/ai/chat接口，SSE 流式响应 - 前端：
ChatBot.tsx+ChatMessage.tsx组件 - 状态管理：
AIContext.tsx管理会话、消息、生成状态
- 后端：
- 特性：
- 流式输出，实时显示 AI 生成过程
- 多会话管理（新建、切换、删除对话）
- 会话历史持久化（localStorage）
- 用户头像调用项目头像接口显示
- 系统提示词包含完整的论坛功能说明
2. 写作辅助功能
- 6 个辅助动作：动作功能提示词polish润色优化使文字表达更流畅、更有文采expand扩写内容增加细节和论述summarize简化缩写提取核心要点grammar语法检查检查语法错误并修正title生成标题生成 3-5 个标题建议outline生成大纲生成内容大纲
- 技术实现：
- 后端：
/api/ai/assist接口，SSE 流式响应 - 前端：
WritingAssistant.tsx组件 - 服务层：
writingService.ts封装流式请求
- 后端：
3. UI 交互设计
- AI 侧边栏（
AISidebar.tsx）：- 右侧可展开/收起的抽屉式面板
- 两个 Tab：人工智能对话 / 写作辅助
- 悬浮触发按钮（
AIToggleButton.tsx）
- 对话界面：
- 会话下拉选择器（支持切换和删除）
- 快捷提问按钮
- 消息气泡样式（用户紫色/AI 灰色）
- 停止生成按钮
- 写作辅助界面：
- 6 个功能按钮网格布局
- 输入文本框
- 结果显示区（流式输出 + 闪烁光标）
- 复制/应用按钮
二、技术架构
┌─────────────────────────────────────────────────────────────┐
│ 前端 (React) │
├─────────────────────────────────────────────────────────────┤
│ AIContext.tsx - 全局状态管理 │
│ ├── sessions - 会话列表 │
│ ├── currentSession - 当前会话 │
│ ├── isGenerating - 生成状态 │
│ └── hasApiKey - API Key 状态 │
│ │
│ ChatBot.tsx - 对话主组件 │
│ ChatMessage.tsx - 消息气泡组件 │
│ WritingAssistant.tsx - 写作辅助组件 │
│ AISidebar.tsx - 侧边栏容器 │
│ │
│ services/ai/ │
│ ├── deepseek.ts - API 调用封装 │
│ ├── chatService.ts - 对话服务 + 系统提示词 │
│ └── writingService.ts - 写作辅助服务 │
└─────────────────────────────────────────────────────────────┘
│
│ HTTP (SSE)
▼
┌─────────────────────────────────────────────────────────────┐
│ 后端 (Express) │
├─────────────────────────────────────────────────────────────┤
│ routes/ai.ts - 路由定义 │
│ ├── GET /check - 检查 API Key 配置 │
│ ├── POST /chat - AI 对话（流式） │
│ └── POST /assist - 写作辅助（流式） │
│ │
│ controllers/aiController.ts - 控制器 │
│ ├── checkApiKey() - 检查配置 │
│ ├── chat() - 对话处理 │
│ └── assist() - 写作辅助处理 │
└─────────────────────────────────────────────────────────────┘
│
│ HTTP (SSE)
▼
┌─────────────────────────────────────────────────────────────┐
│ AI API (SiliconFlow) │
├─────────────────────────────────────────────────────────────┤
│ URL: https://api.siliconflow.cn/v1/chat/completions │
│ Model: deepseek-ai/DeepSeek-V3 │
│ Stream: true │
└─────────────────────────────────────────────────────────────┘
三、遇到的技术问题及解决方案
问题 1：后端流式响应但前端一次性显示
- 现象：后端从 AI API 收到流式数据，但前端等全部完成才显示
- 原因：后端收集完整结果后才调用
res.json()返回 - 解决方案：typescript
// 后端改为 SSE 流式响应 res.setHeader('Content-Type', 'text/event-stream'); res.setHeader('Cache-Control', 'no-cache'); res.setHeader('Connection', 'keep-alive'); res.setHeader('X-Accel-Buffering', 'no'); // 每收到 chunk 立即发送 res.write(`data: ${JSON.stringify({ content })}\n\n`);
问题 2：SSE 数据没有立即发送到前端
- 现象：后端
res.write()后数据被缓冲，没有立即到达前端 - 原因：Express 响应缓冲机制
- 解决方案：typescript
res.flushHeaders(); // 立即发送响应头 // 写入后尝试 flush if (typeof (res as any).flush === 'function') { (res as any).flush(); }
问题 3：前端收到流式数据但 UI 不实时更新
- 现象：控制台显示数据正在接收，但页面不更新
- 原因：React 18 自动批处理（Automatic Batching）将多次
setState合并 - 尝试方案 1：使用
flushSync强制同步更新 —— 无效 - 最终解决方案：使用
useRef直接操作 DOMtypescriptconst resultRef = useRef<HTMLDivElement>(null); // 流式回调中直接更新 DOM onChunk: (chunk) => { accumulated += chunk; if (resultRef.current) { resultRef.current.textContent = accumulated; } }
问题 4：AI 助手不了解项目实际功能
- 现象：用户问”如何更换头像”，AI 回答”不支持自定义头像”
- 原因：系统提示词不准确，没有包含完整的功能说明
- 解决方案：更新
chatService.ts中的FORUM_ASSISTANT_PROMPT，详细列出：- 发帖功能（分类、Markdown、图片上传、草稿）
- 互动功能（点赞、收藏、回复、楼中楼）
- 个人中心（自定义上传头像、修改昵称、查看记录）
- 消息功能（通知、私信）
- 搜索、主题切换等
问题 5：对话删除按钮不显示
- 现象：下拉菜单中的删除按钮看不到
- 原因：
opacity: 0+group-hover:opacity-100的 Tailwind 类在内联样式组件中不生效 - 解决方案：改用内联样式 +
onMouseEnter/onMouseLeave事件控制透明度
四、关键配置
环境变量（后端 .env ）
env
AI_API_URL=https://api.siliconflow.cn
AI_API_KEY=sk-xxx
AI_MODEL=deepseek-ai/DeepSeek-V3
前端 API 地址
typescript
const API_BASE = import.meta.env.VITE_API_URL || '/api';
五、文件清单
| 文件路径 | 说明 |
|---|---|
backend/src/controllers/aiController.ts | AI 接口控制器 |
backend/src/routes/ai.ts | AI 路由定义 |
src/contexts/AIContext.tsx | AI 全局状态管理 |
src/components/ai/AISidebar.tsx | AI 侧边栏容器 |
src/components/ai/AIToggleButton.tsx | 侧边栏触发按钮 |
src/components/ai/ChatBot.tsx | 对话主组件 |
src/components/ai/ChatMessage.tsx | 消息气泡组件 |
src/components/ai/WritingAssistant.tsx | 写作辅助组件 |
src/services/ai/deepseek.ts | API 调用封装 |
src/services/ai/chatService.ts | 对话服务 + 系统提示词 |
src/services/ai/writingService.ts | 写作辅助服务 |
src/types/ai.ts | AI 相关类型定义 |
六、功能截图
