在 Astro Firefly 主题中集成专属 AI 智能助手：从 API 配置到 UI 落地全记录

2026-10-31T00:00:00.000Z

在搭建独立博客的过程中，为访客提供一个轻量、实时且懂你网站的 AI 助手一直是许多独立开发者的心愿。今天这篇文章，就带大家把一个非intrusive（不唐突）、支持上下文问答与文章摘要的 AI 聊天小组件，完美集成到基于 Astro 的 Firefly 主题中。

技术栈选型#

前端框架：Astro (SSR 动态渲染模式)
部署托管：Vercel Serverless Functions
AI 引擎：Groq API (选用高性价比且高效的 openai/gpt-oss-20b 模型)
UI 交互：原生 Tailwind CSS + 浮动卡片交互，完美兼容 Swup 无刷新跳转

后端 API 接口实现 (`src/pages/api/ai.ts`)#

为了保证安全性，我们不能把 API Key 暴露在前端。因此，我们需要在 Astro 中创建一个后端的 Serverless 接口。

这里我们不仅实现了基础的聊天问答，还加入了针对长文章的 AI 摘要功能，以及一套全能文本清洗逻辑——用来彻底过滤掉大模型偶尔“抽风”吐出的 Markdown 表格管道符（|）和多余符号，确保在纯文本聊天框中排版清爽。

在项目的 src/pages/api/ 目录下创建 ai.ts 文件：

1
import type { APIRoute } from 'astro';
2

3
export const prerender = false;
4

5
// 🧹 全能文本清洗函数：确保在纯文本气泡中格式清爽、多余 Markdown 符号彻底被清除
6
function cleanAiResponse(text: string): string {
7
  if (!text) return "";
8

9
  let cleaned = text;
10

11
  // 1. 转换表格管道符为竖向列表
12
  if (cleaned.includes('|')) {
13
    const lines = cleaned.split('\n');
14
    const formattedLines: string[] = [];
15
    for (const line of lines) {
16
      if (line.replace(/[\s|:\-]+/g, '') === '') continue;
17
      if (line.includes('|')) {
18
        const parts = line.split('|').map(p => p.trim()).filter(Boolean);
19
        if (parts.length > 0) {
20
          formattedLines.push(`• ${parts.join('：')}`);
21
        }
22
      } else {
23
        formattedLines.push(line);
24
      }
25
    }
26
    cleaned = formattedLines.join('\n');
27
  }
28

29
  // 2. 清除裸露的反引号和粗体符号
30
  cleaned = cleaned.replace(/`/g, '');
31
  cleaned = cleaned.replace(/\*\*/g, '');
32

33
  // 3. 确保列表项前自带换行，防止粘连
34
  cleaned = cleaned.replace(/([^\n])\s*[-•]\s*/g, '$1\n• ');
35
  cleaned = cleaned.replace(/([^\n])\s*(\d+\.)\s*/g, '$1\n$2 ');
36

37
  return cleaned.trim();
38
}
39

40
export const POST: APIRoute = async ({ request }) => {
41
  try {
42
    const apiKey = import.meta.env.GROQ_API_KEY || process.env.GROQ_API_KEY;
43

44
    if (!apiKey) {
45
      return new Response(
46
        JSON.stringify({ result: "服务器未配置 API Key，请检查 Vercel 环境变量设置。" }),
47
        { status: 200, headers: { 'Content-Type': 'application/json' } }
48
      );
49
    }
50

51
    const body = await request.json();
52
    const { action, prompt, text } = body;
53

54
    let systemPrompt = "";
55
    let userContent = "";
56

57
    if (action === 'summary') {
58
      systemPrompt = "你是一个专业的博客文章摘要助手。请为以下文章生成一段结构清晰、内容充实的摘要，字数控制在 150~200 字左右，包含文章的核心观点和主要干货，语言亲切自然，不要使用表格。";
59
      userContent = (text || "").slice(0, 3000);
60
    } else {
61
      systemPrompt = `你是「喵栈 AI」小助手，专为独立博客「早安喵栈 (929255.xyz)」服务。
62
【核心规则】：
63
1. 语言亲切可爱，控制在 100 字以内。
64
2. 遇到列表或多项说明时，每条内容必须换行输出（使用 - 或 • 开头）。
65
3. 严禁使用表格，严禁输出反引号或粗体符号。
66

67
【本站背景与精准指引】：
68
- 站点核心技术：Astro 静态博客框架、Tailwind CSS 自定义样式、Vercel 自动化部署、GitHub 托管、Cloudflare CDN 加速、Markdown/MDX 写作。
69
- 若询问“有哪些文章推荐”：请推荐本站关于 Astro 博客配置、Vercel 部署实践、Docker/Gatus 自建服务和独立博客搭建的探索记录。
70
- 若询问“怎么搭建类似博客”：简要列出使用 Astro、Tailwind CSS、Vercel 与 GitHub 部署的步骤。`;
71

72
      userContent = prompt || "你好";
73
    }
74

75
    // 封装带自动重试的 Groq 请求函数（应对 429 或 500 抖动）
76
    async function fetchWithRetry(retries = 2, delay = 1000): Promise<any> {
77
      try {
78
        const response = await fetch('https://api.groq.com/openai/v1/chat/completions', {
79
          method: 'POST',
80
          headers: {
81
            'Authorization': `Bearer ${apiKey}`,
82
            'Content-Type': 'application/json'
83
          },
84
          body: JSON.stringify({
85
            model: 'openai/gpt-oss-20b',
86
            messages: [
87
              { role: 'system', content: systemPrompt },
88
              { role: 'user', content: userContent }
89
            ],
90
            temperature: 0.2,
91
            max_tokens: 800
92
          })
93
        });
94

95
        if (!response.ok) {
96
          const errText = await response.text();
97
          if ((response.status === 429 || response.status >= 500) && retries > 0) {
98
            await new Promise(resolve => setTimeout(resolve, delay));
99
            return fetchWithRetry(retries - 1, delay * 2);
100
          }
101
          throw new Error(`Groq 状态码 ${response.status}: ${errText}`);
102
        }
103

104
        return await response.json();
105
      } catch (error) {
106
        if (retries > 0) {
107
          await new Promise(resolve => setTimeout(resolve, delay));
108
          return fetchWithRetry(retries - 1, delay * 2);
109
        }
110
        throw error;
111
      }
112
    }
113

114
    const data = await fetchWithRetry();
115
    const rawResult = data.choices?.[0]?.message?.content || "";
116

117
    const aiResult = cleanAiResponse(rawResult);
118

119
    if (!aiResult.trim()) {
120
      return new Response(
121
        JSON.stringify({ result: "喵~ AI 刚才走神了，请再点一次发送试试！" }),
122
        { status: 200, headers: { 'Content-Type': 'application/json' } }
123
      );
124
    }
125

126
    return new Response(
127
      JSON.stringify({ result: aiResult }),
128
      { status: 200, headers: { 'Content-Type': 'application/json' } }
129
    );
130

131
  } catch (error: any) {
132
    console.error("❌ AI API 内部错误:", error);
133
    return new Response(
134
      JSON.stringify({ result: "网络开小差啦，请稍后再提问~" }),
135
      { status: 200, headers: { 'Content-Type': 'application/json' } }
136
    );
137
  }
138
};

展开收起

前端悬浮挂件与 UI 落地 (`Layout.astro` 或根布局)#

为了让所有页面都能在左下角展示这个可爱的 AI 悬浮球，我们在全局布局文件（例如 Firefly 主题的根 Layout 中）加入了挂件的 HTML 结构与交互脚本。

1. HTML 与样式组件#

在布局文件的底部（之前）加入悬浮窗 DOM：

1
2
<div id="ai-widget" class="fixed bottom-6 left-6 z-50">
3
  
4
  <div id="ai-box" class="hidden w-[360px] h-[460px] mb-4 rounded-2xl border border-black/10 dark:border-white/10 card-base shadow-2xl flex flex-col overflow-hidden text-neutral-800 dark:text-neutral-200">
5
    
6
    <div class="px-4 py-3 border-b border-black/10 dark:border-white/10 flex justify-between items-center bg-black/5 dark:bg-white/5">
7
      <div class="flex items-center gap-2.5">
8
        <div class="w-7 h-7 rounded-lg bg-teal-500/20 border border-teal-500/30 flex items-center justify-center text-teal-600 dark:text-teal-400 text-sm">🐱div>
9
        <span class="font-semibold text-sm text-neutral-900 dark:text-white">喵栈 AIspan>
10
        <span class="text-[10px] px-2 py-0.5 rounded-full bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border border-emerald-500/20 font-medium">在线span>
11
      div>
12
      <div class="flex items-center gap-3 text-neutral-500 dark:text-neutral-400 text-xs">
13
        <button id="ai-clear" class="hover:text-black dark:hover:text-white transition-colors" title="清空对话">🗑️button>
14
        <button id="ai-close" class="hover:text-black dark:hover:text-white text-base leading-none transition-colors">✕button>
15
      div>
16
    div>
17

18
    
19
    <div id="ai-messages" class="flex-1 p-4 overflow-y-auto space-y-3.5 text-xs leading-relaxed">
20
      <div class="flex gap-2">
21
        <div class="w-6 h-6 rounded-md bg-teal-500/20 text-teal-600 dark:text-teal-400 flex items-center justify-center text-xs shrink-0">🐱div>
22
        <div class="space-y-3">
23
          <div class="bg-black/5 dark:bg-white/5 border border-black/5 dark:border-white/5 p-3 rounded-2xl rounded-tl-none max-w-[90%] text-neutral-800 dark:text-neutral-200 whitespace-pre-wrap">
24
            喵~ 我是「喵栈 AI」小助手，专门为早安喵栈 (929255.xyz) 服务。有什么想问的吗？
25
          div>
26
          
27
          <div class="flex flex-wrap gap-2 pt-1" id="ai-quick-prompts">
28
            <button class="quick-btn px-3 py-1.5 rounded-full bg-black/5 hover:bg-black/10 dark:bg-white/5 dark:hover:bg-white/10 border border-black/10 dark:border-white/10 text-neutral-700 dark:text-neutral-300 text-[11px] transition-all hover:scale-[1.02] active:scale-95">
29
              这个博客用了什么技术？
30
            button>
31
            <button class="quick-btn px-3 py-1.5 rounded-full bg-black/5 hover:bg-black/10 dark:bg-white/5 dark:hover:bg-white/10 border border-black/10 dark:border-white/10 text-neutral-700 dark:text-neutral-300 text-[11px] transition-all hover:scale-[1.02] active:scale-95">
32
              有哪些文章推荐？
33
            button>
34
            <button class="quick-btn px-3 py-1.5 rounded-full bg-black/5 hover:bg-black/10 dark:bg-white/5 dark:hover:bg-white/10 border border-black/10 dark:border-white/10 text-neutral-700 dark:text-neutral-300 text-[11px] transition-all hover:scale-[1.02] active:scale-95">
35
              怎么搭建类似的博客？
36
            button>
37
          div>
38
        div>
39
      div>
40
    div>
41

42
    
43
    <div class="p-3 border-t border-black/10 dark:border-white/10 bg-black/5 dark:bg-white/5 flex gap-2 items-center">
44
      <input id="ai-input" type="text" placeholder="向喵栈 AI 提问..." class="flex-1 bg-black/5 dark:bg-white/5 border border-black/10 dark:border-white/10 rounded-xl px-3.5 py-2 text-neutral-900 dark:text-white placeholder-neutral-400 dark:placeholder-neutral-500 outline-none focus:border-black/30 dark:focus:border-white/30 text-xs transition-colors" />
45
      <button id="ai-send" class="bg-black/10 hover:bg-black/20 dark:bg-white/15 dark:hover:bg-white/25 text-neutral-900 dark:text-white px-3.5 py-2 rounded-xl text-xs font-medium transition-all active:scale-95">发送button>
46
    div>
47
  div>
48

49
  
50
  <button id="ai-toggle" class="w-12 h-12 rounded-full card-base border border-black/10 dark:border-white/10 shadow-2xl flex items-center justify-center text-xl hover:scale-110 active:scale-95 transition-transform">
51
    🐱
52
  button>
53
div>

展开收起

早安喵栈

在 Astro Firefly 主题中集成专属 AI 智能助手：从 API 配置到 UI 落地全记录

技术栈选型#

后端 API 接口实现 (src/pages/api/ai.ts)#

前端悬浮挂件与 UI 落地 (Layout.astro 或根布局)#

1. HTML 与样式组件#

后端 API 接口实现 (`src/pages/api/ai.ts`)#

前端悬浮挂件与 UI 落地 (`Layout.astro` 或根布局)#