flight-scout
该 skill 目录通常会附带一个 .env.example 模板文件。
推荐做法：
- 使用官方安装脚本完成安装或更新；脚本会保留现有
.env，只同步受管理文件 - 如果手动安装，请根据
.env.example创建本地.env - 本地
.env用于保存真实接口密钥，不应提交到版本库
本地 .env 里通常包含：
FLIGHT_SCOUT_API_BASE_URLFLIGHT_SCOUT_API_KEYFLIGHT_SCOUT_API_TIMEOUT_SECONDS
脚本行为：
scripts/call_api.py会优先自动读取 skill 根目录下的.env- 如果当前 shell 已经显式设置了同名环境变量，则以显式环境变量为准
读取以下环境变量：
FLIGHT_SCOUT_API_BASE_URLFLIGHT_SCOUT_API_KEYFLIGHT_SCOUT_API_TIMEOUT_SECONDS，默认30
调用前必须确认：
- 出发机场三字码
- 到达机场三字码
- 日期
- 舱位与乘客数（如未给出，默认
economy和1）
优先使用脚本：
示例命令：
python3 {baseDir}/scripts/call_api.py search --origin HKG --destination NRT --date 2026-05-01
python3 {baseDir}/scripts/call_api.py calendar --origin PVG --destination CDG --date-start 2026-07-03 --date-end 2026-07-15
接口选择规则：
- 普通航班搜索：调用
search - 机场联想补全：调用
airport-search - 日期区间最低价：调用
calendar - 甩尾票接口选择：
- 如果需要同步直接返回结果，调用
hidden-city-sync - 如果接受异步任务和轮询，调用
hidden-city-job-create - 不需要先调用
hidden-city-sync再决定是否发起hidden-city-job-create - 选择依据主要是“是否需要即时结果”和“调用额度消耗”，不是先做命中判断
- 如果需要同步直接返回结果，调用
- 用量汇总：调用
usage - 当用户询问“已用多少额度 / 剩余多少额度 / 什么时候重置”时，优先调用
usage - 如果业务接口返回
quota_exceeded，继续读取meta.remaining_units、meta.cycle_ends_at、meta.upgrade_required
结果处理要求：
- 直接返回接口 JSON，不要重写字段名
- 如果接口返回错误，保留
request_id、error.code、error.message - 额度相关字段优先读取
data.quota.*；如果是额度拦截错误，则读取meta.remaining_units、meta.included_units、meta.cycle_ends_at - 如果使用异步 job，明确告诉用户当前
job_id和状态 - 如果使用同步查询，就按同步结果直接说明；如果使用异步 job，就按任务状态与最终结果说明
详细接口字段见 references/api-contract.md