介绍
# Air France (AFKL Open Data) flight tracker
## 快速开始（一次性状态查询）
1) 创建 API 密钥（及可选的密钥） - 注册网址：https://developer.airfranceklm.com - 订阅您所需的 Open Data 产品（至少需要 **Flight Status API**） - 生成凭证（API 密钥；部分账户还会提供 API 密钥）
2) 提供 API 凭证（请勿打印）： - 推荐方式：环境变量 `AFKL_API_KEY`（及可选的 `AFKL_API_SECRET`） - 或者在您的状态目录（`CLAWDBOT_STATE_DIR` 或 `./state`）中的文件： - `afkl_api_key.txt`（chmod 600） - `afkl_api_secret.txt`（chmod 600，可选）
2) 查询航班状态： - 运行：`node skills/airfrance-afkl/scripts/afkl_flightstatus_query.mjs --carrier AF --flight 7 --origin JFK --dep-date 2026-01-29`
备注： - 发送 `Accept: */*`（API 返回 `application/hal+json`）。 - 保持在限制内：**<= 1 请求/秒**。在进行多次调用时，每次调用之间暂停约 1100ms。
## 开始监控（监视器）
适用于用户希望主动接收更新的情况。
- 运行：`node skills/airfrance-afkl/scripts/afkl_watch_flight.mjs --carrier AF --flight 7 --origin JFK --dep-date 2026-01-29`
其功能： - 获取日期窗口内的运营航班。 - 仅在有实质性变化时发送一条消息。 - 还会追溯 **前一航班的链**（`flightRelations.previousFlightData.id`）至可配置的深度，并在前一航段延误或取消时发出警报。
轮询策略（默认）： - 起飞前 >36h：最多每 **60 分钟** - 36h→12h：每 **30 分钟** - 12h→3h：每 **15 分钟** - 3h→起飞：每 **5–10 分钟**（保持在每日配额内） - 起飞后：每 **30 分钟** 直至抵达
实现细节：每 5–15 分钟运行一次 cron，但脚本使用状态文件进行自我限流，因此不会在非必要时间调用 API。如果没有任何变化，监视器 **无输出**（因此 cron 作业仅在 stdout 非空时发送邮件）。
## 输入简写
推荐的用户友好格式： - `AF7 demain` / `AF7 jeudi`
解析规则： - 日期始终指 **出发日期**（而非到达日期）。
实现说明： - 将相对日期词转换为用户时区的出发日期，除非明确已知始发地时区。 - 当存在歧义时（跨越午夜的长途航班），如果已知始发地，则优先采用始发地的本地出发日期。
（对于脚本，仍需传递 `--origin` + `--dep-date YYYY-MM-DD`。）
## 解析“有意义的”字段
请参阅 `references/fields.md` 了解： - `flightRelations`（前一/后一） - `places.*`（航站楼/登机口/值机区域） - `times.*`（计划/预计/最新/实际） - `aircraft`（型号，注册号） - “停机位” / 停机类型提示（如果存在） - Wi‑Fi 提示以及如何推断客舱的新旧程度
## 客舱新旧程度 / 升舱启发式规则
当飞机注册号可用时： - 使用尾号推断 **子机队** 和可能的客舱代际。 - 如果数据表明配置较旧（或没有 Wi‑Fi），升级可能更值得或不那么值得。
保持保守： - Open Data 通常不公开确切的座椅型号；请将其视为 **尽力而为** 的信息。