Biz Next.js Chatbot OpenRouter — 一鍵安裝 AI 聊天機器人浮動視窗到網站 是做什麼的？
這項技能會將一個 AI 聊天機器人浮動小工具 安裝到您現有的 Next.js 專案中。小工具位於右下角，在三個螢幕尺寸上都具有完整的響應式設計。它透過 OpenRouter 呼叫 LLM，並使用您提供的 FAQ + 課程/產品文件作為知識庫。在機器人對話氣泡中，它使用 react-markdown + remark-gfm 渲染 Markdown 格式（數字/價格的粗體、項目符號清單、可點擊的連結、行內程式碼）。當使用者在聊天中提供完整資訊時，系統會自動擷取並儲存潛在客戶名單（姓名 + 電話 + 電子郵件）到 KV 儲存（Upstash Redis / Vercel KV）中。管理員可以透過 /admin 儀表板檢視這些名單。目標是：讓個人創業者 / 課程創作者能夠在銷售課程的登陸頁面上，擁有24/7 自動支援機器人 + 被動式客戶名單擷取，不錯過任何透過聊天來詢問的客戶。
核心理念：自動偵測所有可能的項目 (Next.js 版本, App/Pages Router, TS/JS, Tailwind/CSS)，只詢問使用者真正需要的 4 件事：(1) 如果有多個專案要選哪個，(2) FAQ，(3) 產品文件，(4) 語調/品牌名稱。其餘的由程式碼搞定→幾分鐘內上線。
何時使用
使用者想要：
- 為銷售課程/服務的登陸頁面添加一個 AI 客戶支援聊天機器人
- 減少回覆重複問題（價格、學習路徑、退款、適合對象...）的負擔
- 需要一個右下角、不遮擋內容的緊湊聊天小工具
- 需要聊天機器人準確理解他們的課程/產品內容（由 FAQ 驅動）
- 已經有一個 Next.js 專案（剛執行完
/biz-sales-page-layout或舊專案）
何時不該使用
- 專案不是 Next.js (純 React Vite, Vue, Svelte, 純 HTML) → 此技能專為 Next.js 設計。可以改寫，但非最佳解。
- 需要具有 RAG（檢索增強生成）且知識庫有數千頁的聊天機器人 → 需要向量資料庫 (Pinecone/Supabase pgvector)，此技能使用簡單的 system prompt，適合 ≤ 20K token 的知識。
- 需要語音/多模態（傳送圖片）聊天機器人 → 此技能僅限文字。
- 需要將每個使用者的聊天記錄儲存到資料庫 → 此技能為無狀態、短暫的 session，但未來可以擴展。
- 後端不適用於 Vercel（需要長輪詢、持久 WebSocket） → OpenRouter 串流在 Vercel Edge 上運行良好，但如果需要專用的 WebSocket 則有所不同。
使用者將獲得的輸出
技能執行完成後：
-
使用者 Next.js 專案中的新檔案：
components/Chatbot.tsx(或.jsx) — 小工具 UI（透過react-markdown+remark-gfm渲染 markdown）app/api/chat/route.ts(App Router) 或pages/api/chat.ts(Pages Router) — 呼叫 OpenRouter 的 API 代理 + 串流結束後自動擷取潛在客戶lib/chatbot-knowledge.ts(或.js) — 知識庫 + system prompt（包含回覆格式區塊 + 主動潛在客戶蒐集區塊）lib/chat-lead.ts— 僅在專案有 KV/Upstash 時建立 — 擷取器與儲存器，根據電話號碼去重，TTL 90 天，命名空間chat-lead:{phone}- Markdown 樣式
.chatbot-md附加到app/globals.css(來自templates/chatbot-markdown-styles.css) - 建立/附加
.env.local，包含OPENROUTER_API_KEY=(預留位置) .env.example(如果尚不存在) 用來記錄環境變數- 將
<Chatbot />掛載到app/layout.tsx或pages/_app.tsx
-
額外安裝的套件 (透過從 lockfile 偵測到的套件管理員)：
react-markdown— 安全地渲染 markdown（不需要dangerouslySetInnerHTML）remark-gfm— GitHub Flavored Markdown (表格、自動連結、刪除線)
-
Session 結束時的明確指引：
- 使用者需要自行完成的 3 個步驟：(a) 取得 OpenRouter API 金鑰，(b) 貼到
.env.local，(c)npm run dev進行測試 - 如何在 Gemini 和 Sonnet 之間切換模型
- 未來如何更新知識庫
- 使用者需要自行完成的 3 個步驟：(a) 取得 OpenRouter API 金鑰，(b) 貼到
工作流程
步驟 1 — 偵測 Next.js 專案
尋找 Next.js 專案候選項目。執行：
# 在 dependencies 中尋找包含 "next" 的 package.json，最大深度為 4
find /Users/tonyhoang/Documents/GitHub -maxdepth 4 -name "package.json" -not -path "*/node_modules/*" 2>/dev/null | xargs grep -l '"next"' 2>/dev/null | head -20
(如果使用者位於特定的工作目錄，則優先從 cwd 向下尋找；如果找不到，則回退到 ~/Documents/GitHub。)
分支判斷：
- 0 個專案：通知使用者並停止。建議：「您有任何 Next.js 專案嗎？如果沒有，希望我先用
/biz-sales-page-layout建立一個新的，然後再回來嗎？」 - 1 個專案：在繼續之前先與使用者確認路徑：「我將把聊天機器人安裝到 [路徑]。可以嗎？」
- ≥ 2 個專案：列出帶有編號的路徑和名稱（來自
package.json的name），讓使用者選擇：「我發現有 N 個 Next.js 專案。您想安裝到哪一個？」
步驟 2 — 探查專案上下文
在使用者確認專案後，讀取：
-
package.json→ 檢查：- TypeScript (deps 中是否有
typescript？) - Tailwind (devDeps 中是否有
tailwindcss？) - 套件管理員 (lockfile:
pnpm-lock.yaml→ pnpm,yarn.lock→ yarn, 預設npm) - Next.js 版本
- TypeScript (deps 中是否有
-
目錄結構 → 檢查：
app/目錄存在 → App Routerpages/目錄存在 (且沒有app/) → Pages Router- 兩者都存在 → 新的檔案優先使用 App Router (Next.js 正在遷移)
src/包裝 → 調整路徑 (例如src/app/,src/components/)
-
tsconfig.json→ 檢查路徑別名 (@/*→./src/*還是./*) -
.env.local,.env.example→ 檢查是否已存在 -
KV/Upstash 可用性 (用於自動潛在客戶擷取)：
package.json中有@upstash/redis或@vercel/kv→ 有 KV → 建立 chat-lead.ts 並連接到路由- 有檔案
src/lib/kv.ts(或lib/kv.ts) 匯出kv→ 直接使用現有的輔助函數 (camp pattern) - 沒有 KV → 跳過建立 chat-lead.ts，通知使用者：「專案尚未設定 KV — 自動潛在客戶擷取未啟用。我可以先執行
/biz-setup-sepay-payment來安裝 KV，然後再回來啟用潛在客戶擷取，或者直接跳過。」
將這些觀察結果記錄成一個小表格，供後續步驟使用。
步驟 3 — 從使用者收集知識庫
向使用者詢問 4 個問題 (合併在一則訊息中，讓使用者一次性回答，減少來回次數)：
為了讓聊天機器人準確回答，我需要 4 樣東西：
1. **FAQ** — 常見問題與解答清單（價格、學習路徑、退款、適用對象、學習時間、課後支援等）。
請直接貼在這裡，或者提供檔案路徑 (.md / .txt / .docx)。
2. **產品/課程文件** — 課程的詳細描述：名稱、每個模組的內容、學習成果、講師、獎勵、多個 tier 的價格。
同樣可以貼上或提供檔案路徑。
3. **品牌名稱 + 語調** — 品牌/課程名稱，讓聊天機器人可以用來稱呼（例如「AI Mastery 的助理」）。機器人使用的語調：友善的「您」(預設) / 正式 / 隨意的「你」。
4. **模型** — 預設為 `google/gemini-3-flash-preview` (快速、便宜、足以應付支援)。想要使用 `anthropic/claude-sonnet-4.6` (品質更高，貴約 10 倍) 還是初期聊天量仍然很低，請告訴我。
您可以一次回答嗎？
當使用者回覆時：
- 如果只提供檔案路徑 → 使用 Read 工具讀取該檔案。
- 如果直接貼上內容 → 使用貼上的內容。
- 如果使用者說「幫我自動生成預留的內容」 → 建立通用的 FAQ 預留位置，並標記
// TODO: user fill in以便使用者知道需要更新。 - 如果沒有品牌名稱 → 預設為「AI 助理」並使用「您」來稱呼。
步驟 4 — 生成檔案到專案中
讀取此技能 templates/ 中的範本，並適配到專案中。範本：
templates/chatbot-knowledge.ts— 匯出知識庫 + systemPrompt 的模組。在此注入 FAQ、產品資訊、品牌名稱和語調。包含回覆格式區塊 (markdown 規則) + 主動潛在客戶蒐集區塊 (教導 LLM 在偵測到購買意圖時索取姓名/電話/電子郵件，當使用者提供時感謝並確認，不要說「已儲存到資料庫」)。templates/Chatbot.tsx— 小工具元件，以 Tailwind 為主。已匯入react-markdown+remark-gfm，使用<ReactMarkdown remarkPlugins={[remarkGfm]}>渲染助手訊息 (僅限助手 — 使用者訊息仍為純文字whitespace-pre-wrap)。如果專案沒有 Tailwind → 回退到templates/Chatbot-noTailwind.tsx+templates/chatbot.module.css。templates/chat-route-app.ts— App Router 的 API 路由 (app/api/chat/route.ts)。包含persistLeadIfReady鉤子，在串流關閉後以 fire-and-forget 方式執行 — 不會阻塞回應。templates/chat-route-pages.ts— Pages Router 的 API 路由 (pages/api/chat.ts)。templates/chat-lead.ts— 僅在專案有 KV/Upstash 時建立 — 使用正則表達式擷取越南電話號碼 + 電子郵件 + 姓名 (啟發式規則，如 "tên X" / "tôi là X" / "tên: X")，saveChatLead根據電話號碼去重，TTL 90 天，金鑰命名空間chat-lead:{phone}。templates/chatbot-markdown-styles.css— 用於類別.chatbot-md的 CSS 程式碼片段。必須附加到app/globals.css(或src/app/globals.css/styles/globals.css) 的結尾。在附加之前，根據專案的品牌調色板更改強調色 (#fde68a/#f59e0b)。templates/env-instructions.md— 取得 OpenRouter 金鑰的說明片段，在最後一步使用。
適配範本時的規則：
-
TS vs JS：如果專案只有 JS，則將副檔名
.ts/.tsx→.js/.jsx並移除型別註解 (不僅是重新命名檔案)。讀取範例檔案，解析，移除型別，然後寫入。 -
路徑別名：如果
tsconfig將@/*映射到./src/*，則範本中的匯入必須使用@/lib/chatbot-knowledge，並且檔案應放置在src/lib/。如果沒有別名，則使用相對路徑。 -
模型：將預留位置
__MODEL_ID__替換為使用者選擇的模型 (google/gemini-3-flash-preview或anthropic/claude-sonnet-4.6)。 -
品牌：替換
__BRAND_NAME__,__BRAND_TUNE__。 -
知識：從 FAQ + 產品資訊中建構
systemPrompt，格式清晰 (參見範本)。保留 systemPrompt 中的回覆格式區塊 — 這是教導 LLM 輸出適合小型聊天氣泡的 markdown (使用粗體代替標題，使用簡短的單行項目符號) 的關鍵。 -
安裝 markdown 渲染套件 (強制 — 如果跳過，聊天機器人會在氣泡中顯示原始的
**bold**而不是粗體)：# 偵測 lockfile → 選擇正確的套件管理員 npm install react-markdown remark-gfm # 或：pnpm add react-markdown remark-gfm # 或：yarn add react-markdown remark-gfm -
附加 markdown 樣式：讀取
templates/chatbot-markdown-styles.css，根據專案的品牌調色板切換強調色 (檢查globals.css尋找--color-primary或類似變數)，然後附加到app/globals.css(或src/app/globals.css/styles/globals.css) 的結尾。 -
掛載小工具：
- App Router：編輯
app/layout.tsx(或src/app/layout.tsx)，加入import Chatbot from '@/components/Chatbot'並在</body>之前加入<Chatbot />。編輯前讀取目前的 layout.tsx 以保留 metadata、字型和 providers。 - Pages Router：編輯
pages/_app.tsx，包裝 return：<><Component {...pageProps} /><Chatbot /></>。先讀取_app，保留現有的 providers。
- App Router：編輯
-
自動潛在客戶擷取連線 (僅在步驟 2 中偵測到 KV 時執行)：
- 將
templates/chat-lead.ts複製到lib/chat-lead.ts(或src/lib/chat-lead.ts)。 - 如果專案尚未有
lib/kv.ts→ 建立：import { Redis } from "@upstash/redis"; export const kv = Redis.fromEnv(); - 路由處理器匯入：
import { extractLeadFromMessages, saveChatLead } from "@/lib/chat-lead"。 - 在串流迴圈中：追蹤
assistantText(累積差異)，當串流關閉時 → 呼叫persistLeadIfReady(history, assistantText)(fire-and-forget，請勿在回應路徑中使用await)。 - System prompt：確保
chatbot-knowledge.ts中已有主動潛在客戶蒐集區塊 (範本中已包含)。 - 向使用者確認：「我已啟用自動潛在客戶擷取 — 當客戶在聊天中貼上姓名/電話/電子郵件時，系統會自動儲存到 KV 命名空間
chat-lead:{電話}。您可以透過/admin檢視潛在客戶 (如果您已安裝/biz-admin-leads-dashboard)。」
- 將
步驟 5 — 設定 .env.local + .gitignore
-
檢查
.env.local是否已存在？- 否：建立新檔案，內容如下：
# OpenRouter API 金鑰 — 請到 https://openrouter.ai/keys 取得 OPENROUTER_API_KEY= # 可選：用於 OpenRouter 追蹤來源的網站 URL (有助於改善速率限制) NEXT_PUBLIC_SITE_URL=http://localhost:3000 - 是：如果上述 2 個變數不存在則附加，不要覆蓋現有變數。
- 否：建立新檔案，內容如下：
-
更新
.env.example(如果不存在則建立)：OPENROUTER_API_KEY=sk-or-v1-xxxxx NEXT_PUBLIC_SITE_URL=https://your-domain.com -
檢查
.gitignore是否已有.env.local？如果沒有 → 附加.env.local和.env*.local。
步驟 6 — 向使用者報告
輸出 1 則清晰的摘要訊息，包含 4 個部分：
✅ 聊天機器人已成功安裝到 [專案名稱]
📁 已建立的檔案：
- components/Chatbot.tsx (透過 react-markdown + remark-gfm 渲染 markdown)
- app/api/chat/route.ts
- lib/chatbot-knowledge.ts
- app/globals.css (附加 markdown 樣式 .chatbot-md)
- .env.local (預留位置)
📦 已安裝的套件：react-markdown, remark-gfm
🔑 您需要自行完成的 3 個步驟，聊天機器人才能運作：
1. 取得 OpenRouter API 金鑰：
- 前往 https://openrouter.ai → 註冊 (可以使用 Google 登入)
- 前往 https://openrouter.ai/keys → 建立金鑰
- 儲值點數 (https://openrouter.ai/credits) — Gemini 3 Flash 很便宜，$5 足夠執行數千次聊天
- 複製格式為 `sk-or-v1-xxxxx` 的金鑰
2. 貼到 `.env.local` 檔案中：
OPENROUTER_API_KEY=sk-or-v1-xxxxx-貼到這裡
3. 執行測試：
[npm/pnpm/yarn] run dev
開啟 http://localhost:3000 → 點擊右下角的泡泡
🔄 在 Gemini ↔ Sonnet 之間切換模型：
開啟 `app/api/chat/route.ts`，修改檔案頂部的 `model:` 變數。
- `google/gemini-3-flash-preview` (預設，$0.075/100 萬輸入 token，快速)
- `anthropic/claude-sonnet-4.6` (進階，約 $3/100 萬輸入 token，品質更好)
📚 日後更新知識庫：
編輯 `lib/chatbot-knowledge.ts` — 新增/修改 FAQ 和 productInfo，儲存，熱重載即可。
行動優先響應式設計
小工具必須達到 3 個斷點：
| 斷點 | 行為 |
|---|---|
| ≤ 640px (手機) | 點擊泡泡 → 開啟全螢幕覆蓋層 (z-index 9999)，標題列有 X 關閉按鈕。輸入框固定在底部，具有 safe-area-inset 以避免被鍵盤遮擋。 |
| 641–1023px (平板) | 面板 380px × 70vh，固定在右下角，邊距 16px。 |
| ≥ 1024px (桌上型) | 面板 400px × 600px，固定在右下角，邊距 24px。泡泡為 60px 圓形。 |
**
…
[為便於翻譯而截斷]