「在 AI Agent 的架構設計中，批次分析腳本負責盤後推播，而 FastAPI Web 服務則提供 Real-time Chat、知識庫動態學習與系統狀態監控。透過異步 Lifespan 託管與 Singletons，能確保 Production 級別的高效能與高穩定度。」

先前，我們相繼完成了 Linux 系統排程設定與盤後自動化腳本的端到端整合測試。今天我們將切換視角，深入 Angelina AI Agent 的 Web 服務核心。
這個 FastAPI 應用程式不僅是前端 Chat UI 的心臟，更是提供 API 端點給批次腳本進行知識庫寫入與狀態監控的中樞系統。
今天我們將解析核心架構、單例服務 Lifespan 託管，以及 /chat 與 /health 端點的實作邏輯！

本篇重點摘要

1. 剖析 Structlog JSON 結構化日誌與 Lifespan 異步單例初始化。
2. 拆解 /health 與 /stats 系統監控 API 端點。
3. 深入解析 /chat 核心對話流程，以及內建的 /learning-stats、/learn 與 /fetch-url 特殊指令處理機制。

一、結構化日誌與 Lifespan 單例服務託管

系統使用了 structlog 進行 JSON 格式的結構化日誌記錄，並透過 FastAPI 的 asynccontextmanager（Lifespan）管理四大核心 Singletons 的 life cycle：

  1. JSON 結構化日誌
     預設將 Log 寫入 /var/log/angelina/app.log，具備權限備援降級（fallback 至 sys.stderr），輸出包含 ISO 時間戳記、Log Level 與 JSON 格式資料，方便集中式日誌追蹤。

  2. 異步 Lifespan 託管 (lifespan)
     啟動階段：依序初始化四大單例服務——ConversationMemory、RAGEngine、GeminiGateway與 LearningModule。
     關閉階段：在服務關閉時優雅釋放 GeminiGateway 的 HTTPAsyncClient 資源，避免連線洩漏。

二、系統監控與健康檢查 API 端點

系統提供了兩個輕量級的 GET 端點，用於 Load Balancer、systemd 診斷與盤後腳本狀態查詢：

  1. 健康檢查端點 (GET /health)

@app.get("/health")
async def health_check() -> dict:
    """Health check endpoint. Returns HTTP 200 with status ok."""
    return {"status": "ok"}

2. 系統統計端點 (GET /stats)
   即時回傳當前對話記憶的 Turn 數量，以及 ChromaDB 向量庫中的 Vector 總數，提供系統可觀測性：

@app.get("/stats")
async def get_stats() -> dict:
    memory_turns = await _memory.get_turn_count()
    vector_count = await _rag_engine.get_collection_count()
    return {"memory_turns": memory_turns, "vector_count": vector_count}

三、核心對話管道：/chat 端點與特殊指令解析

POST /chat 是整個應用程式最繁忙的核心端點。除了常規對話外，它還內建了三種強大的特殊指令解析：

  1. Special Commands
     /learning-stats：查詢目前 Agent 自動學習模組產出的知識點統計（此端點在 Day 25 盤後腳本的 [2/6] 步驟中被呼叫）。
     /learn <content>：允許使用者或批次腳本直接將純文字切碎並寫入向量庫（此端點在 Day 25 盤後腳本的 [7/7] 步驟中被呼叫）。
     /fetch-url <url>：透過 httpx 抓取指定網頁 HTML，過濾 <script> 與 <style> 標籤純化後，自動分區段加入知識庫。

  2. 標準 6 步驟對話處理流程
     當收到一般對話訊息時，chat() 函式執行以下管線：
        (1) 載入上下文：從 ConversationMemory 讀取近 20 輪歷史對話。
        (2) 語意檢索：呼叫 RAGEngine 進行 Top-5 語意 search。若無匹配 Chunk 則自動將 used_general_knowledge 標記為 True。
        (3) 呼叫 Gemini API：透過 GeminiGateway 生成回覆，並進行極限保護（捕捉 GeminiQuotaExhaustedError 回傳 HTTP 429、捕捉 GeminiTimeoutError 回傳 HTTP 504）。
        (4) 記憶持久化：將 User 與 Assistant 的對話記錄同步存回 ConversationMemory。
        (5) 構建 Response：將生成的文本與參考資料來源（SourceRef）包裝為 ChatResponse。
        (6) 異步後台學習：透過 asyncio.create_task() 觸發背景非阻斷任務，讓 LearningModule 自動從 Agent 的回答中萃取知識點寫回知識庫。

四、記憶清理與知識庫重建端點

也提供了管理員級別的特權控制端點：

  1. 清除歷史記憶
     呼叫 _memory.clear_history()，若成功刪除則回傳成功訊息；若刪除失敗則保留紀錄並回傳錯誤警示。

  2. 知識庫重構
     掃描 data/notebooklm/ 目錄下的最新資料導出檔，自動觸發 _rag_engine.rebuild_index() 進行重新分塊、重新 Embedding 與索引替換。

五、今日總結

透過對 code 解析，我們確認了：

  1. 雙管道整合：FastAPI 既是前端即時對話的 API 提供者，也是盤後自動化腳本進行知識查詢與回寫的中樞。
  2. 高韌性架構：Lifespan 單例託管、JSON 結構化日誌，以及後台非阻斷式學習機制，確保了服務的高併發與高穩定性。

明日預告：敬請期待期待~!