工程日记・第二天：打造一个让其他 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 在每次响应中都返回数据、洞察和机会。这就是数据库查询和关系之间的区别。