法国航空（AFKL Open Data）航班追踪器

快速入门（单次状态查询）

1. 创建 API 密钥（及可选的密钥密文）

• 注册地址：https://developer.airfranceklm.com
• 订阅所需 Open Data 产品（至少需订阅 Flight Status API）
• 生成凭据（API key；部分账号还会提供 API secret）

2. 提供 API 凭据（请勿直接打印输出）：

• 推荐方式：通过环境变量设置 AFKL_API_KEY（以及可选的 AFKL_API_SECRET）
• 或存为文件于 state 目录中（CLAWDBOT_STATE_DIR 或 ./state）：
  • afkl_api_key.txt（权限设为 600）
  • afkl_api_secret.txt（权限设为 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。

启动持续监控（watcher）

适用于用户希望获得主动式状态更新的场景。

• 执行命令：node skills/airfrance-afkl/scripts/afkl_watch_flight.mjs --carrier AF --flight 7 --origin JFK --dep-date 2026-01-29

功能说明：

• 获取指定日期窗口内的实际运营航班信息。
• 仅当发生有意义的状态变更时，才输出一条消息。
• 同时沿用 前序航班链（即 flightRelations.previousFlightData.id）向上追溯至可配置的深度，并在任一前序航段出现延误或取消时发出告警。

轮询策略（默认）：

• 起飞前 36 小时起：最多每 60 分钟 一次

• 起飞前 36 小时至 12 小时：每 30 分钟 一次
• 起飞前 12 小时至 3 小时：每 15 分钟 一次
• 起飞前 3 小时至起飞时刻：每 5–10 分钟 一次（需确保不超出日配额）
• 起飞后至抵达前：每 30 分钟 一次

实现细节：cron 任务按每 5–15 分钟运行一次，但脚本内部通过 state 文件进行自限流控制，确保未到轮询时间点时不会调用 API。该 watcher 在无状态变化时不输出任何内容（因此 cron 可配置为仅在 stdout 非空时触发通知）。

输入简写支持

推荐面向用户的简写格式：

• AF7 demain / AF7 jeudi

解析规则：

• 所指日期始终为 出发日期（而非到达日期）。

实现说明：

• 将相对日期词（如 “demain”、“jeudi”）转换为用户所在时区的出发日期，除非已明确获知出发地时区。
• 对于跨子夜的长途航班等存在歧义的情形，若出发地已知，则优先采用出发地本地时间对应的出发日期。

（对脚本调用，仍须显式传入 --origin 和 --dep-date YYYY-MM-DD 参数。）

关键字段语义解析

详见 references/fields.md 中关于以下字段的说明：

• flightRelations（前序/后续航班关系）
• places.*（值机区、登机口、航站楼等位置信息）
• times.*（计划/预估/最新/实际时间）
• aircraft（机型、注册号）
• 停机位（parking position）及停机类型（stand-type）提示（如存在）
• Wi‑Fi 支持提示，以及客舱新旧程度推理方法

客舱新旧程度判断与升舱启发式策略

当可获取飞机注册号时：

• 利用尾号推断所属 子机队，进而估计其客舱代际水平。
• 若数据显示为较老配置（或无 Wi‑Fi），则升舱决策的价值可能相应提升或降低。

注意事项（保守原则）：

• Open Data 通常不暴露具体座椅型号，相关判断应视为 尽力而为（best-effort）。