Article Analyzer

Appearance

Feature Specification: RAG 智慧問答整合 ​

Feature Branch: 012-rag-chatbot-integration

Created: 2026-06-10

Status: Implemented

Input: 在現有 scrape-analyzer 系統中整合 RAG（檢索增強生成）功能，讓使用者能透過對話介面詢問與已爬取文章相關的問題，系統以語意搜尋配合智慧回答回應使用者。

User Scenarios & Testing (mandatory) ​

User Story 1 — 文章問答（內嵌輸入欄）(Priority: P1) ​

使用者在閱讀文章列表頁面時，可以直接在頁面上方或特定區域看到一個問答輸入欄。輸入自然語言問題後，系統會根據已爬取的文章內容，以語意搜尋找出最相關的段落，並由智慧回答服務生成一段有根據的回覆，同時附上引用來源。

Why this priority: 這是 RAG 功能的核心體驗。在頁面中直接提供問答能力，讓使用者無需離開主流程即可獲得知識摘要，直接體現 RAG 功能的核心價值。

Independent Test: 可獨立測試：在文章列表頁輸入問題，確認系統回覆且附有文章來源引用。

Acceptance Scenarios:

  1. Given 使用者在文章列表頁，When 在問答輸入欄輸入「最近有哪些關於 LLM 效能的研究？」並送出，Then 系統在合理時間內回傳一段回覆，並附上至少一篇相關文章作為來源。
  2. Given 使用者輸入與已爬取文章完全無關的問題，When 送出查詢，Then 系統回覆「找不到相關資料」或類似提示，而非捏造答案。
  3. Given 使用者輸入空白問題，When 嘗試送出，Then 系統不送出請求，並提示使用者輸入問題內容。

User Story 2 — 浮動聊天機器人（右下角圖示）(Priority: P2) ​

使用者在任何頁面瀏覽時，畫面右下角固定顯示一個聊天機器人圖示。點擊後展開對話視窗，可與系統進行多輪對話。對話過程中，系統維持同一會話的上下文，使用者可以追問或深入探討前一個問題的答案，且引用的文章來源一起呈現在對話紀錄中。

Why this priority: 浮動聊天機器人提供更豐富的多輪對話體驗，補足單次問答的不足；但核心 RAG 能力（P1）需要先穩定才能支撐此體驗。

Independent Test: 可獨立測試：在任意頁面點擊右下角圖示，展開聊天視窗並進行至少兩輪對話，確認系統在第二輪能理解前一輪的語境。

Acceptance Scenarios:

  1. Given 使用者在任意頁面，When 點擊右下角聊天機器人圖示，Then 展開一個對話視窗，且不影響目前頁面的瀏覽。
  2. Given 使用者已在對話視窗中問了「最近 LLM 有什麼新研究？」，When 接著問「這些研究有什麼實際應用？」（不重複主題），Then 系統能理解「這些研究」指前一問題的結果，並給出前後連貫的回答。
  3. Given 使用者關閉對話視窗後再次打開，When 在同一個瀏覽器會話中，Then 系統保留本次會話的對話紀錄。

User Story 3 — 文章向量化（Pipeline 整合）(Priority: P1) ​

當爬取系統完成一篇文章的全文獲取後（不論來源為 PDF、Blog 或 RSS），系統自動將全文切分為適當的語意片段，並將每個片段的語意向量儲存至向量資料庫，供後續問答使用。此流程對現有 Pipeline 透明，不影響原有的分析與通知流程。

Why this priority: 向量化是 RAG 問答的資料基礎。沒有向量資料，問答服務無從檢索，因此與 P1 的問答功能並列最高優先。

Independent Test: 可獨立測試：執行一次完整爬取，之後查詢向量資料庫確認對應文章的片段已存入。

Acceptance Scenarios:

  1. Given 爬取 Pipeline 完成一篇新文章的全文獲取，When 文章進入處理流程，Then 該文章的語意片段在 Pipeline 完成後可在向量資料庫中查到。
  2. Given Pipeline 向量化步驟發生錯誤，When 錯誤被捕捉到，Then 現有的文章分析與通知流程繼續正常執行，不因向量化失敗而中斷。
  3. Given 同一篇文章被重複處理（如重新爬取），When 觸發向量化，Then 系統不重複儲存相同內容的向量片段（冪等性）。

Edge Cases ​

  • 當文章全文極短（例如少於 100 字）時，系統如何處理切片？
  • 當問答服務暫時無法連線時，問答介面應如何顯示錯誤訊息而不讓頁面崩潰？
  • 當使用者在短時間內連續送出多個問題時，系統如何處理並發請求？
  • 當文章內容包含多種語言時，語意搜尋是否能跨語言比對？
  • 當向量資料庫中尚無任何資料（系統剛建立）時，問答介面應如何提示使用者？
  • 當爬取結果為機器人偵測頁面（如「請啟用 JavaScript」、「Access Denied」）時，系統必須跳過向量化，不儲存無效內容。

Requirements (mandatory) ​

Functional Requirements ​

Pipeline 整合（向量化）

  • FR-001: 系統必須在文章全文獲取完成後，自動觸發語意切片與向量儲存流程，不需人工介入。
  • FR-002: 系統必須支援 PDF、Blog HTML、RSS 純文字等不同來源格式的全文向量化。
  • FR-003: 向量化流程必須具備冪等性，重複處理同一篇文章不會造成向量資料庫中的重複記錄。
  • FR-004: 向量化流程發生錯誤時，必須記錄錯誤並讓現有 Pipeline 繼續執行，不得中斷文章分析或通知流程。
  • FR-005: 每個向量片段必須關聯到來源文章的識別資訊（至少包含文章 ID 與原文 URL），以便回答時引用來源。

後端問答服務

  • FR-006: 系統必須提供一個問答端點，接收使用者問題後，執行語意搜尋並生成有根據的回答。
  • FR-007: 問答回答必須附帶引用來源（文章標題與連結），讓使用者可驗證答案出處。
  • FR-008: 當問題無法在現有文章向量庫中找到相關內容時，系統必須明確告知使用者「找不到相關資料」，不得憑空捏造答案。
  • FR-009: 問答服務必須支援多輪對話，能在同一會話中維持對話上下文，讓追問邏輯通順。
  • FR-010: 問答服務必須整合外部 RAG SDK，由外部套件負責語意搜尋與回答生成的核心邏輯；本系統僅負責整合與資料路由。

前端介面

  • FR-011: 前端必須在指定頁面顯示一個問答輸入欄，讓使用者輸入問題並即時顯示回答。

  • FR-012: 前端必須在所有頁面的右下角顯示一個固定浮動的聊天機器人 FAB。已登入用戶或明示啟用「訪客模式」的用戶點擊後展開對話視窗；未認證且未啟用訪客模式的用戶不顯示 FAB。

  • FR-013: 對話視窗必須保留對話紀錄，使用 localStorage（以 userId 標記）跨標籤頁持久化；用戶登出時自動清除，防止不同用戶間歷史洩漏。

  • FR-014: 前端問答元件必須使用外部套件（@s091648/chatbot-plugin-ui）提供的 useChat hook 與 AgentInput 元件；浮動聊天視窗 UI（FloatingChatbotPanel）為本系統自行實作，外部套件的 ChatbotPlugin 元件不使用。

  • FR-015: 前端問答介面必須在問答服務不可用時顯示適當的錯誤提示，不影響頁面其他功能。

  • FR-016: 問答功能對所有訪客開放，但系統必須依照使用者身份施加每日請求次數上限（RPD）：訪客每日最多 3 次、一般登入會員每日最多 10 次、管理員無限制。超過限制時，系統必須回傳明確的提示訊息（HTTP 429），而非靜默失敗。系統必須提供 GET /chat/quota 端點，讓前端查詢目前剩餘次數與上限，供 UI 顯示配額資訊。

Key Entities ​

  • 向量片段（VectorChunk）: 代表一篇文章中的一個語意片段，包含片段文字、對應的語意向量、來源文章 ID、來源 URL、片段順序索引。
  • 問答會話（ChatSession）: 代表一次使用者的對話會話，包含會話 ID（瀏覽器端生成）、問題與回答的歷史紀錄列表。
  • 問答訊息（ChatMessage）: 代表對話中的單則訊息，包含訊息角色（使用者 / 系統）、內容、時間戳記、引用來源列表。

Success Criteria (mandatory) ​

Measurable Outcomes ​

  • SC-001: 問答功能的首次回答在使用者送出問題後 10 秒內 完成，90% 的查詢符合此標準。
  • SC-002: 文章完成爬取後，其向量片段在 Pipeline 完成的 5 分鐘內 可供問答系統使用。
  • SC-003: 問答回答的引用準確率達 90% 以上（回答中引用的來源文章確實與問題相關）。
  • SC-004: 向量化流程失敗時，現有文章分析與通知流程的成功率維持在 99% 以上（不受向量化錯誤影響）。
  • SC-005: 使用者在對話視窗中進行 3 輪以上追問，系統能維持前後連貫的對話脈絡，不需重複說明背景。
  • SC-006: 前端問答元件在問答服務不可用時，100% 的情況顯示明確的錯誤提示，不崩潰或顯示技術錯誤訊息。

Assumptions ​

  • 假設外部 RAG SDK Python 套件已存在且可透過套件管理工具安裝；本系統不需自行實作語意切片、向量化或檢索邏輯。
  • 假設外部前端問答元件套件已存在且提供可設定後端服務 URL 的介面；本系統不需自行開發聊天介面元件。
  • 假設向量資料庫服務為獨立部署的外部服務（非本 monorepo 管理），本系統僅需設定連線資訊。
  • 假設問答功能初版（v1）不需支援串流式回答（Streaming response）；完整回答一次性返回即可。
  • 假設多輪對話的上下文由外部 RAG SDK 或問答服務管理，前端僅需傳遞對話歷史列表。
  • 假設跨語言語意搜尋（如繁體中文問題匹配英文文章）由外部 RAG SDK 的 Embedding 模型負責，本系統不額外處理語言轉換。
  • 假設問答功能初版不需 Tool Use / MCP / Skills 整合，這些為未來迭代範疇。