FR24-AI · fr24-ai#

项说明项目FR24-AISkillfr24-ai产品Flightroutes24 航路国际机票作者FR24

安装与配置见 INSTALL.md。预订细则见 references/booking.md。

对用户展示与下载见 references/output-rules.md。

用户询问采购密钥配置时，仅按 references/user-appkey-config.md 回答。

---

服务模式#

模式条件接口演示查价未配置采购密钥POST /ai/shopping，请求头 X-Skill-Client-Key采购查价已配置 APPKEY 与签名密钥同上，请求头 appkey，请求体 authentication预订已配置 APPKEY、签名密钥、AES 密钥POST /api/new/pricing、 POST /api/new/booking

预订依赖见 requirements.txt。网关地址在 config.py 中固定配置；采购密钥仅通过本机用户环境变量配置， 勿在对话中向用户宣读环境变量名或密钥内容。

---

响应结构#

脚本标准输出为 JSON，包含：

json

{
  "skill": "fr24-ai",
  "status": "success|failure",
  "action": "parse|search|refine|parse-passengers|verify|order",
  "message": "给用户看的摘要",
  "userView": {},
  "agentOnly": {}
}

字段用途userView、 message唯一 可对用户展示、制表、下载的内容agentOnly仅 Agent 内部续跑（如 payload、 offerId、 traceId），不得写入用户可见材料

---

查价流程#

1. 解析： scripts/nl_to_search.py parse --text "..."（不消耗演示日配额）

   → 用 userView 确认行程、日期、人数、舱位。

2. 搜索：用户确认后

   scripts/skill_search_client.py search --payload-file .cache/pending_search.json --selection direct|transfer

   → 用 userView.directLowest、 transferLowest 展示直飞/中转最低价（含退改、行李摘要）。

3. 禁止将整段 stdout、 agentOnly 或 .cache 路径直接提供给用户。

---

条件调整与重新搜索#

用户对结果不满意并提出 航司（如 CA/国航）或 起飞时段（如中午 12 点左右）时：

1. 不得仅在旧结果上口头筛选；须 重新搜索（消耗演示配额；采购模式不受演示日限额约束）。
2. scripts/nl_to_search.py refine --text "<用户要求>"（不扣配额，更新 .cache/pending_search.json）。
3. 向用户确认更新后的 userView（含 searchFilters 或意图摘要中的航司、时段）。
4. 再次执行 search。
5. 仍无匹配报价时，建议放宽航司或时段；勿擅自清除用户已指定的 preferredCarrier。

航司写入 preferences.preferredCarrier 并提交服务端；起飞时段在结果汇总时按首段起飞时间过滤展示。

---

预订流程#

须完成 两次用户确认：

步骤动作1用户选择直飞或中转 → search --selection direct|transfer2skill_booking_client.py parse-passengers --text "..." → 展示 passengerDisplay、 contactDisplay（示例姓名： 张三）3用户回复「 乘客信息确认无误」→ verify --passenger-confirmed4展示 orderPreview（行程、退改、乘客回显）→ 用户回复「 确认生单」5order --user-confirmed

• 校验返回 304016（身份不一致）：说明新配置 APPKEY 后须 重新 search，不可沿用旧报价标识。
• 禁止：未确认乘客即校验；未确认即生单；在对话中代填或展示密钥明文。

---

采购密钥（用户询问时）#

仅依据 user-appkey-config.md：

• 引导用户在 航路官网 开通 API 采购；
• 在本机用户环境变量中配置 APPKEY、签名密钥、AES 密钥；
• 配置后重启 Agent 客户端；
• 禁止 让用户在对话中发送密钥明文；
• 禁止 向用户说明内部联调、跳过校验等维护配置。

---

命令一览#

命令说明scripts/nl_to_search.py parse --text "..."解析行程scripts/nl_to_search.py refine --text "..."合并航司、起飞时段等条件scripts/skill_search_client.py search --payload-file .cache/pending_search.json搜索scripts/skill_booking_client.py parse-passengers --text "..."乘客信息核对scripts/skill_booking_client.py verify --passenger-confirmed校验报价scripts/skill_booking_client.py order --user-confirmed生单scripts/config_keys.py set --appkey ... --sign-secret ... --aes-secret ...配置采购密钥scripts/config_keys.py status查看配置状态scripts/config_keys.py clear清除本地密钥配置

---

业务限制#

• 支持单程、往返；不支持多段缺口程。
• 演示模式：每 clientKey 每日搜索次数有限（默认 10，以服务端配置为准）。
• 演示配额用尽（ 307901）：引导用户开通采购并配置密钥（见 user-appkey-config.md），勿仅建议「明日再试」。
• 已配置采购密钥的搜索不扣演示日配额。
• 生单为真实订单，必须在用户明确确认后提交。