AI 聊天助手设计文档

日期： 2026-03-02 状态： 已批准

需求背景

为 VitePress 文档站（AI精品店）添加 AI 聊天功能，AI 能自主搜索文档内容并回答用户问题。

技术方案

轻量 RAG（检索增强生成）方案：

• 无向量数据库，构建时生成 JSON 索引
• 前端用 fuse.js 做全文检索
• Vercel Edge Function 代理 LLM 请求（保护 API Key）
• 支持流式输出

架构

构建阶段：
  VitePress buildEnd hook
    → 遍历所有 .md 文件
    → 生成 docs-index.json → 输出到 dist/

运行时：
  ChatWidget.vue (右下角悬浮按钮)
    → 用户提问
    → fuse.js 本地检索 docs-index.json，取 top 3 相关文档片段
    → POST /api/chat { question, context }
    → Vercel Edge Function (api/chat.ts)
        → 拼装 system prompt + context
        → 调用 AI HUB API (OpenAI 兼容格式，流式)
        → 流式返回给前端
    → 前端逐字渲染回答

文件变更

新增文件

• api/chat.ts — Vercel Edge Function，代理 AI 请求，持有 API Key
• docs/.vitepress/theme/components/ChatWidget.vue — 聊天浮窗 Vue 组件

修改文件

• docs/.vitepress/config.ts — 添加 buildEnd hook，遍历 md 文件生成 docs-index.json
• docs/.vitepress/theme/index.ts — 将 ChatWidget 注册到 layout-bottom 插槽

环境变量（存 Vercel，不进 Git）

变量名	说明
AI_CHAT_API_KEY	AI HUB API Key
AI_CHAT_API_URL	API 基础地址（如 https://api.codexzh.com）
AI_CHAT_MODEL	使用的模型名

关键设计决策

文档索引

• 遍历 docs/ 下所有 .md 文件，跳过 index.md
• 每篇文档截取前 1500 字符（控制索引大小）
• 输出字段：path、title、content、category

检索策略

• fuse.js 搜索 title（权重高）+ content
• threshold: 0.4
• 返回 top 3 结果，拼装为 LLM context

Edge Function 设计

• 接收：{ question: string, context: string }
• 输入长度限制：question ≤ 500 字符，防滥用
• 转发到 AI HUB API（OpenAI 兼容格式）
• 开启 stream: true，将流直接透传给前端

安全考量

• API Key 仅存在 Vercel 环境变量，不暴露给浏览器
• Edge Function 做输入长度校验

依赖

npm install fuse.js gray-matter

• fuse.js — 前端全文检索
• gray-matter — 解析 markdown frontmatter（构建时用）