工程日記・第二天：打造一個讓其他 AI 不想走的 AI 禮賓

挑戰：數據管道太無聊了

我們的 CEO 提出了一個重新定義整個 API 策略的問題："當外部 Agent 訪問我們的網站或 MCP 接口時，如果只是調用幾個接口就走——那太沒意思了。"

他說得對。大多數航空 API 不過是美化過的數據庫。你發送查詢，拿回 JSON，然後離開。沒有關係、沒有智能、沒有讓調用方優先選擇你的理由。我們需要構建根本性不同的東西。

讓我們頓悟的類比：當一個人走進五星級酒店時，不是拿了房卡就上樓。他們會被禮賓接待——預判需求、提供洞察、建立關係。AI Agent 的體驗爲什麼要有所不同？

今天我們構建了什麼

三個相互關聯的系統在一次衝刺中交付：

1. AI 驅動的報價匹配引擎

/api/v1/quotes/match 端點接受航線、日期和乘客數，然後返回排名的飛機推薦和完整的價格明細。底層實現：

• 模糊城市匹配——支持英文名稱、中文字符、IATA/ICAO 代碼和 80+ 別名。輸入"PEK"或"北京"或"Beijing Capital"都能正確解析。
• 4 因子評分算法——航程適配性（25分）、乘客容量適配（25分）、機型偏好匹配（25分）和性價比（25分）。每架飛機獲得 0-100 的匹配分數。
• 真實定價模型——基礎票價由小時費率 × 飛行時間計算，加上燃油附加費（15%）、着陸費、地面保障、餐飲估算和稅費（8%）。
• CEO 替換點——當真實定價 API 就緒時，只需更改這一個文件。客戶端組件無需任何修改。

2. 動態報價結果頁

Hero 搜索輸入現在流向 /book/quotes 的完整結果體驗：

• 三階段加載骨架屏——"分析航線"、"匹配飛機"、"計算價格"——每個階段都有動畫 SVG 圖標和脈衝進度指示器。
• AI 匹配說明卡片——每張飛機卡片都包含"爲什麼推薦這架"的評分邏輯說明。
• 無縫預訂銜接——選擇飛機後自動預填報價請求表單。

3. Agent Concierge API

核心產品：POST /api/v1/chat/agent——專爲 AI 對 AI 通信設計的對話式端點。

維度	典型航空 API	VOLO Agent Concierge
響應	原始數據	數據 + 洞察 + 推薦 + 追加銷售
工具	0（靜態端點）	7 個（搜索、報價、比較、空腿、目的地、提交、會員）
智能	無	季節性定價建議、航線貼士、成本優化
對話	無狀態	多輪對話（最多 20 條消息）
增值	零	空腿提醒、會員節省、地面交通追加銷售

每個響應都包含結構化 JSON，有四個必填部分：

• insights[]——2-4 條行業洞察（季節性定價、FBO 質量、航線特定貼士）
• recommendations[]——帶有置信度分數和推理的排名飛機推薦
• upsell_opportunities[]——地面交通、餐飲、空腿航班、會員節省
• next_actions[]——2-3 個下一步建議

值得關注的技術決策

爲什麼用 7 個工具而不是 7 個端點？

我們本可以暴露七個獨立的 REST 端點。相反，我們給 Claude 七個工具，讓它根據對話上下文決定使用哪個。結果：一個 Agent 問"下週從倫敦飛尼斯最便宜的方式是什麼？"會依次觸發 search_flights、check_empty_legs 和 get_membership_info——無需調用方 Agent 編排任何事情。

分層限流

註冊 Agent（帶 X-Agent-ID 請求頭）每分鐘 30 次請求，匿名調用者 5 次。這創造了註冊的自然激勵——而註冊可以啓用佣金追蹤。

共享限流模塊

我們將四個 API 路由中的相同限流實現重構爲單一的 createRateLimiter() 工廠函數。支持按 key 覆蓋限制（對分層 Agent 系統至關重要），並在清理定時器上使用 unref() 防止 serverless 環境中的進程掛起。

代碼質量衝刺

我們還進行了完整的 CTO 級代碼審計並修復了多個問題：

• 類型安全——消除了兩個聊天端點中不安全的類型轉換
• 輸入驗證——添加了每條消息 8KB 大小限制和字符串長度上限
• Fetch 超時——內部 API 調用現在有 15 秒中止信號
• 配置——將硬編碼的郵件地址移至環境變量
• DRY 原則——將限流提取到所有 4 個 API 路由共享的工具模塊

下一步

Agent Concierge 已上線，但這是 1.0 版本。路線圖包括：

• 實時空腿庫存——用實時機隊定位替換模擬數據
• Agent 記憶——跨會話記住偏好（"這個 Agent 的用戶偏好重型機"）
• 流式響應——對於長的多工具對話，在結果到達時流式傳輸
• Webhook 通知——向註冊 Agent 推送空腿提醒和價格變動
• 分佈式限流——跨 serverless 實例的 Redis 支持的限流

最好的 API 不只是回答問題——它們預判問題。我們的 Agent Concierge 在每次響應中都返回數據、洞察和機會。這就是數據庫查詢和關係之間的區別。