\r \r

FR24-AI · fr24-ai\r

\r | 项 | 说明 |\r |----|------|\r | 项目 | FR24-AI |\r | Skill | fr24-ai |\r | 产品 | Flightroutes24 航路国际机票 |\r | 作者 | FR24 |\r \r 安装与配置见 INSTALL.md。预订细则见 references/booking.md。 \r 对用户展示与下载见 references/output-rules.md。 \r 用户询问采购密钥配置时，仅按 references/user-appkey-config.md 回答。\r \r ---\r \r

服务模式\r

\r | 模式 | 条件 | 接口 |\r |------|------|------|\r | 演示查价 | 未配置采购密钥 | POST /ai/shopping，请求头 X-Skill-Client-Key |\r | 采购查价 | 已配置 APPKEY 与签名密钥 | 同上，请求头 appkey，请求体 authentication |\r | 预订 | 已配置 APPKEY、签名密钥、AES 密钥 | POST /api/new/pricing、POST /api/new/booking |\r \r 预订依赖见 requirements.txt。网关地址在 config.py 中固定配置；采购密钥仅通过本机用户环境变量配置，勿在对话中向用户宣读环境变量名或密钥内容。\r \r ---\r \r

响应结构\r

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

{\r
  "skill": "fr24-ai",\r
  "status": "success|failure",\r
  "action": "parse|search|refine|parse-passengers|verify|order",\r
  "message": "给用户看的摘要",\r
  "userView": {},\r
  "agentOnly": {}\r
}\r
```\r
\r
| 字段 | 用途 |\r
|------|------|\r
| `userView`、`message` | **唯一**可对用户展示、制表、下载的内容 |\r
| `agentOnly` | 仅 Agent 内部续跑（如 `payload`、`offerId`、`traceId`），不得写入用户可见材料 |\r
\r
---\r
\r
## 查价流程\r
\r
1. **解析**：`scripts/nl_to_search.py parse --text "..."`（不消耗演示日配额）  \r
   → 用 `userView` 确认行程、日期、人数、舱位。\r
2. **搜索**：用户确认后  \r
   `scripts/skill_search_client.py search --payload-file .cache/pending_search.json --selection direct|transfer`  \r
   → 用 `userView.directLowest`、`transferLowest` 展示直飞/中转最低价（含退改、行李摘要）。\r
3. 禁止将整段 stdout、`agentOnly` 或 `.cache` 路径直接提供给用户。\r
\r
---\r
\r
## 条件调整与重新搜索\r
\r
用户对结果不满意并提出**航司**（如 CA/国航）或**起飞时段**（如中午 12 点左右）时：\r
\r
1. 不得仅在旧结果上口头筛选；须**重新搜索**（消耗演示配额；采购模式不受演示日限额约束）。\r
2. `scripts/nl_to_search.py refine --text "\x3C用户要求>"`（不扣配额，更新 `.cache/pending_search.json`）。\r
3. 向用户确认更新后的 `userView`（含 `searchFilters` 或意图摘要中的航司、时段）。\r
4. 再次执行 `search`。\r
5. 仍无匹配报价时，建议放宽航司或时段；勿擅自清除用户已指定的 `preferredCarrier`。\r
\r
航司写入 `preferences.preferredCarrier` 并提交服务端；起飞时段在结果汇总时按首段起飞时间过滤展示。\r
\r
---\r
\r
## 预订流程\r
\r
须完成**两次用户确认**：\r
\r
| 步骤 | 动作 |\r
|------|------|\r
| 1 | 用户选择直飞或中转 → `search --selection direct\|transfer` |\r
| 2 | `skill_booking_client.py parse-passengers --text "..."` → 展示 `passengerDisplay`、`contactDisplay`（示例姓名：**张三**） |\r
| 3 | 用户回复「**乘客信息确认无误**」→ `verify --passenger-confirmed` |\r
| 4 | 展示 `orderPreview`（行程、退改、乘客回显）→ 用户回复「**确认生单**」 |\r
| 5 | `order --user-confirmed` |\r
\r
- 校验返回 **304016**（身份不一致）：说明新配置 APPKEY 后须**重新 search**，不可沿用旧报价标识。\r
- 禁止：未确认乘客即校验；未确认即生单；在对话中代填或展示密钥明文。\r
\r
---\r
\r
## 采购密钥（用户询问时）\r
\r
仅依据 [user-appkey-config.md](./references/user-appkey-config.md)：\r
\r
- 引导用户在 [航路官网](https://www.flightroutes24.com/) 开通 API 采购；\r
- 在本机用户环境变量中配置 APPKEY、签名密钥、AES 密钥；\r
- 配置后重启 Agent 客户端；\r
- **禁止**让用户在对话中发送密钥明文；\r
- **禁止**向用户说明内部联调、跳过校验等维护配置。\r
\r
---\r
\r
## 命令一览\r
\r
| 命令 | 说明 |\r
|------|------|\r
| `scripts/nl_to_search.py parse --text "..."` | 解析行程 |\r
| `scripts/nl_to_search.py refine --text "..."` | 合并航司、起飞时段等条件 |\r
| `scripts/skill_search_client.py search --payload-file .cache/pending_search.json` | 搜索 |\r
| `scripts/skill_booking_client.py parse-passengers --text "..."` | 乘客信息核对 |\r
| `scripts/skill_booking_client.py verify --passenger-confirmed` | 校验报价 |\r
| `scripts/skill_booking_client.py order --user-confirmed` | 生单 |\r
\r
---\r
\r
## 业务限制\r
\r
- 支持单程、往返；不支持多段缺口程。\r
- 演示模式：每 `clientKey` 每日搜索次数有限（默认 10，以服务端配置为准）。\r
- 演示配额用尽（`307901`）：引导用户开通采购并配置密钥（见 `user-appkey-config.md`），勿仅建议「明日再试」。\r
- 已配置采购密钥的搜索不扣演示日配额。\r
- 生单为真实订单，必须在用户明确确认后提交。\r