AI-Chat 模块技术文档

静态资源：

public/assets/ai-chat/
├── avatar.svg       # AI 头像
├── close.svg        # 关闭按钮图标
├── sparkle.svg      # 建议问题图标
├── attachment.svg   # 附件按钮图标
├── send.svg         # 发送按钮（未激活）
└── send-active.svg  # 发送按钮（激活）

组件详解

1. ChatButton — 浮动按钮

路径：src/components/ai-chat/ChatButton.tsx
类型：Client Component ('use client')

页面右下角可拖拽的浮动 AI 助手按钮。

功能细节

DragState 类型

interface DragState {
    offsetX: number;   // 指针相对按钮左上角的 x 偏移
    offsetY: number;   // 指针相对按钮左上角的 y 偏移
    startX: number;    // 按下时的 clientX
    startY: number;    // 按下时的 clientY
    moved: boolean;    // 是否真正拖拽（>3px 阈值）
}

2. ChatModal — 聊天弹窗

路径：src/components/ai-chat/ChatModal.tsx
类型：Client Component ('use client')
Props：ChatModalProps — { open: boolean; onClose: () => void }

核心聊天容器，管理完整对话生命周期。

主要功能

a) 动画控制

使用 mounted + visible 双状态实现 300ms 缩放淡入淡出：

1. open = true：先 setMounted(true) 挂载 DOM，两帧 RAF 后 setVisible(true) 触发 CSS transition
2. open = false：先 setVisible(false) 触发退出动画，300ms 后 setMounted(false) 卸载 DOM

b) 消息持久化

c) 消息发送流程

handleSend(content)
  │
  ├─ 防重入检查 (sendingRef)
  ├─ 创建 user 消息 + assistant 占位消息 (status: 'sending')
  ├─ 追加到消息列表
  ├─ 调用 callAi({ prompt, knowledgeBase: getSystemPrompt(locale) })
  │
  ├─ code === 200 成功
  │   ├─ 切换 status → 'typing'
  │   ├─ 设置 typingText → 启动 useTypewriter
  │   └─ 打字机逐字更新 content
  │
  ├─ 业务错误码
  │   ├─ rate_limit_exceeded  → t('errorRateLimit')
  │   ├─ too_many_requests    → t('errorTooMany')
  │   ├─ invalid_fingerprint  → t('errorFingerprint')
  │   └─ 其他                 → t('errorGeneric')
  │   └─ status → 'error'
  │
  └─ 网络异常 (catch)
      └─ status → 'error', content → t('errorNetwork')

d) 打字机效果

• 使用 useTypewriter(typingText, { speed: 15 }) hook
• visibleText 变化 → 实时更新消息 content（逐字渲染）
• done = true → status 切换为 'done'

e) 欢迎界面（无消息时）

• 头像 (/assets/ai-chat/avatar.svg)
• 问候语 + 副标题（来自国际化）
• 3 条建议问题按钮（来自 t.raw('suggestions')），点击直接发送

f) 其他细节

3. MessageList — 消息列表

路径：src/components/ai-chat/MessageList.tsx
Props：MessageListProps — { messages: ChatMessage[] }

• 渲染所有消息，每条通过 MessageItem 组件渲染
• 自动滚底：messages 变化时 scrollIntoView({ behavior: 'instant' })（用 instant 避免打字机高频更新时抖动）

4. MessageItem — 消息项

路径：src/components/ai-chat/MessageItem.tsx
Props：MessageItemProps — { message: ChatMessage }

根据 role 和 status 渲染不同样式：

Markdown 渲染通过 useMemo + renderMarkdown(markdown-client.ts) 实现，支持标题、段落、列表、加粗、链接、代码块、引用、表格。

5. ChatInput — 输入框

路径：src/components/ai-chat/ChatInput.tsx
Props：ChatInputProps — { onSend: (content: string) => void }

• <textarea> 多行输入，2 行高度
• Enter 发送，Shift+Enter 换行
• 发送按钮：有内容时显示激活图标 (send-active.svg)，无内容时灰色 (send.svg) + disabled
• 附件按钮（占位，当前未实现附件功能）

Hooks

useTypewriter — 打字机效果

路径：src/hooks/useTypewriter.ts

function useTypewriter(
    fullText: string,
    options?: { speed?: number; enabled?: boolean }
): {
    visibleText: string;   // 当前可见文本（逐字递增）
    done: boolean;         // 是否输出完毕
    skip: () => void;      // 跳至末尾
}

• 使用 setInterval 每 15ms 输出一个字符
• fullText 变化时自动重置
• enabled = false 时直接显示全部文本

服务层

ai-call.ts — AI 调用服务

路径：src/services/ai-call.ts

核心 API 调用层，封装会话管理逻辑。

类型定义

interface AiCallParams {
    prompt: string;
    knowledgeBase?: string;    // 仅首次创建会话时发送
    model?: string;
    temperature?: number;
    max_tokens?: number;
}

interface AiCallResult {
    result: string;            // AI 回复文本
    model: string;             // 使用的模型
    session_id?: string;       // 会话 ID
}

interface AiError {
    error: string;             // 错误码
}

interface AiCallResponse {
    code: number;              // 业务状态码（200 成功）
    data: AiCallResult | null;
    msg: string;
}

会话管理

模块级变量（跨组件实例共享，刷新后从 localStorage 恢复）：

let sessionId: string | null;
let knowledgeBaseSent: boolean;

会话流程：

首次调用               后续调用             会话失效
─────────            ─────────            ─────────
发送 knowledge_base   携带 session_id      error: session_not_found
  ↓                    ↓                    ↓
后端创建会话          后端续接对话          resetSession()
  ↓                    ↓                    ↓
返回 session_id       knowledge_base       下次调用自动重建
  ↓                   （后端已有）
本地保存

跨天自动重置：日期变化时清除 wxzg_chat_session。

请求详情

POST /wxzg/ai-call
Headers:
  x-device-fingerprint: <浏览器指纹>
  Content-Type: application/json
Body:
  {
    prompt: string,                    // 必填，用户输入
    knowledge_base?: string,           // 仅首轮
    session_id?: string,               // 续接时携带
    model?: string,
    temperature?: number,
    max_tokens?: number
  }

validateStatus: () => true  // 不按 HTTP 状态码抛异常，统一由业务 code 字段判断

fingerprint.ts — 浏览器指纹

路径：src/lib/fingerprint.ts

• 使用 @fingerprintjs/fingerprintjs（动态 import，避免 SSR 报错）
• 单例模式：首次调用时加载并缓存 visitorId
• SSR 安全：typeof window === 'undefined' 时返回空字符串

export async function getFingerprint(): Promise<string>

http.ts — HTTP 客户端

路径：src/lib/http.ts

export const http = axios.create({
    timeout: 60_000,  // AI 接口响应较慢，60 秒超时
});

经过 next.config.ts rewrites 代理，前端请求同源地址无需配置 baseURL。

system-prompt.ts — 系统提示词

路径：src/lib/system-prompt.ts

包含中英文两套知识库 + 回复规则，作为 knowledge_base 参数发送给后端（仅首轮）。

export function getSystemPrompt(locale: string): string
// locale === 'zh' → 中文知识库
// 其他 → 英文知识库

知识库内容（压缩版，原始出处 public/docs/knowledge-base.md）：

• 公司概况
• 8 款核心产品表
• 定制开发能力
• AI 应用
• 公司优势
• 合作模式
• 技术栈
• FAQ 精选（10 条）

回复规则（8 条）：

1. 专业顾问口吻，结合业务场景说明
2. 开发需求 → 引导描述业务场景
3. 复杂项目 → 引导加 WhatsApp
4. 需求模糊 → 标准引导语
5. 报价 → 引导提供项目信息
6. 试用 → 标准 SaaS 可试用，定制可看演示
7. 无法回答 / 要求人工 → 引导联系客服
8. 非业务问题 → 礼貌拒绝并引导

markdown-client.ts — Markdown 渲染

路径：src/lib/markdown-client.ts

浏览器端 Markdown → HTML 渲染器，使用 marked 库 + 自定义 Renderer。

支持元素及对应 Tailwind 样式：

export function renderMarkdown(md: string): string

类型定义

chat.ts — 核心消息类型

路径：src/types/chat.ts

type ChatRole = 'assistant' | 'user';

type ChatMessageStatus = 'sending' | 'typing' | 'done' | 'error';

interface ChatMessage {
    content: string;
    id: string;
    role: ChatRole;
    /** 仅 assistant 消息有效 */
    status?: ChatMessageStatus;
}

状态流转：

sending  →  typing  →  done       （正常流程）
sending  →  error                  （异常流程）

AI Chat 组件 Props

路径：src/types/ai-chat.ts

interface FloatingPosition { x: number; y: number }
interface DragState { offsetX: number; offsetY: number; startX: number; startY: number; moved: boolean }
interface ChatModalProps { onClose: () => void; open: boolean }
interface MessageListProps { messages: ChatMessage[] }
interface MessageItemProps { message: ChatMessage }
interface ChatInputProps { onSend: (content: string) => void }

国际化文案

命名空间：aiChat

后端接口规范

POST /wxzg/ai-call

请求

POST /wxzg/ai-call
Content-Type: application/json
X-Device-Fingerprint: <visitorId>

请求体：

{
    "prompt": "string（必填，用户输入的问题）",
    "knowledge_base": "string（可选，知识库内容，仅首次请求携带，用于创建会话）",
    "session_id": "string（可选，会话 ID，续接对话时携带）",
    "model": "string（可选，模型名称）",
    "temperature": "number（可选，温度参数）",
    "max_tokens": "number（可选，最大 token 数）"
}

首次调用示例（创建会话）：

{
    "prompt": "万象自构有哪些产品？",
    "knowledge_base": "【万象自构 - 知识库】\n\n## 公司概况\n..."
}

后续调用示例（续接会话）：

{
    "prompt": "能定制开发吗？",
    "session_id": "sess_abc123"
}

成功响应

{
    "code": 200,
    "msg": "success",
    "data": {
        "result": "您好！万象自构目前有 8 款核心产品...",
        "model": "gpt-4o",
        "session_id": "sess_abc123"
    }
}

错误响应

{
    "code": 429,
    "msg": "rate limit exceeded",
    "data": {
        "error": "rate_limit_exceeded"
    }
}

错误码映射：

后端需要实现的关键逻辑

1. 会话创建（首次调用）

   • 收到 knowledge_base → 创建新会话
   • 将 knowledge_base 作为 system message 注入对话上下文
   • 生成并返回 session_id

2. 会话续接（后续调用）

   • 收到 session_id → 查找已有会话
   • 自动注入已存储的 system message（无需前端重复发送 knowledge_base）
   • 将 user prompt 追加到对话历史，调用 LLM 生成回复
   • 返回更新后的对话结果，同时返回 session_id

3. 会话过期处理

   • 会话不存在或过期时，返回 code !== 200 + data.error: "session_not_found"
   • 前端收到此错误后自动重置状态，下次调用重新创建会话

4. 设备指纹验证

   • 读取请求头 x-device-fingerprint
   • 可用于频率限制、风控等

5. 频率限制

   • 按设备指纹或 IP 实现每日使用次数限制
   • 超限时返回 rate_limit_exceeded
   • 短时间高频请求返回 too_many_requests

6. 跨天重置

   • 按自然日重置使用次数计数
   • 会话在当天有效，跨天后可能需要重新创建（根据会话过期策略决定）

数据存储

localStorage 键一览

Cookie

无 Cookie 写入（当前不涉及非必要 Cookie）。

会话生命周期

用户打开弹窗
  │
  ├─ 从 localStorage 恢复当天消息（如有）
  │
  ├─ 用户发送第一条消息
  │   └─ POST /wxzg/ai-call
  │       body: { prompt, knowledge_base: <系统提示词> }
  │       → 后端创建会话 → 返回 session_id
  │
  ├─ 用户发送后续消息
  │   └─ POST /wxzg/ai-call
  │       body: { prompt, session_id }
  │       → 后端续接会话，自动注入 system message
  │
  ├─ session_not_found
  │   └─ resetSession() → 下次调用自动重建
  │
  └─ 次日打开
      └─ 跨天检测 → 清除消息 + 重置会话

错误处理